import Callout from '@/components/Callout'
import { Steps, Tabs } from 'nextra/components'
import Image from 'next/image'
import VideoPlayer from "@/components/VideoPlayer";

# Managed Auth Quickstart

Pipedream Connect is the easiest way for your users to connect to [over {process.env.PUBLIC_APPS}+ APIs](https://pipedream.com/apps), **right in your product**. You can build in-app messaging, CRM syncs, AI agents, [and much more](/connect/use-cases), all in a few minutes.

## Visual overview

Here's a high-level overview of how Connect works with your app:

<br />
<Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1724194758/Screenshot_2024-08-20_at_3.59.05_PM_rfylfq.png" alt="Pipedream Connect overview" width={800} height={529} />

Here's how Connect sits in your frontend and backend, and communicates with Pipedream's API:

<br />
<Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1723834101/docs/Screenshot_2024-08-16_at_11.48.15_AM_kijxa7.png" alt="Connect developer flow" width={800} height={500} />


## Getting started

<Steps>

### Run the Pipedream example app or configure your own

You'll need to do two things to add Pipedream Connect to your app:

1. [Connect to the Pipedream API from your server](#generate-a-short-lived-token). This lets you make secure calls to the Pipedream API to initiate the account connection flow and retrieve account credentials. If you're running a JavaScript framework like Node.js on your server, you can use the Pipedream SDK.
2. [Add the Pipedream SDK to your frontend](#connect-your-users-account) or redirect your users to [a Pipedream-hosted URL](/connect/connect-link) to start the account connection flow.

We'll walk through these steps below, using [an example Next.js app](https://github.com/PipedreamHQ/pipedream-connect-examples/tree/master/managed-auth-basic-next-app/). To follow along, clone [the repo](https://github.com/PipedreamHQ/pipedream-connect-examples/) and follow the instructions in [the app's `README`](https://github.com/PipedreamHQ/pipedream-connect-examples/tree/master/managed-auth-basic-next-app/). That will run the app on `localhost:3000`.

<Callout type="info">
The Next.js app is just an example. You can build Connect apps in any framework, using any language. We've provided examples in Python, Ruby, and others below.
</Callout>

First, copy the `.env.example` file to `.env.local`:

```bash
cp .env.example .env.local
```

and fill the `.env.local` file with your project and app details:

```bash
# Used by `app/server.ts` to authorize requests to the Pipedream API — see below
PIPEDREAM_CLIENT_ID=your_client_id
PIPEDREAM_CLIENT_SECRET=your_client_secret
PIPEDREAM_PROJECT_ENVIRONMENT=development
PIPEDREAM_PROJECT_ID=your_project_id
```

If you're building your own app, you'll need to provide these values to the environment, or retrieve them from your secrets store.

### Create a project in Pipedream

1. Open an existing Pipedream project or create a new one at [https://pipedream.com/projects](https://pipedream.com/projects).
2. Click the **Settings** tab, then copy your **Project ID**.

### Create a Pipedream OAuth client

Pipedream uses OAuth to authorize requests to the REST API. To create an OAuth client:

1. Visit the [API settings](https://pipedream.com/settings/api) for your workspace.
2. Click the **New OAuth Client** button.
3. Name your client and click **Create**.
4. Copy the client secret. **It will not be accessible again**. Click **Close**.
5. Copy the client ID from the list.

You'll need these when configuring the SDK and making API requests.

### Generate a short-lived token

To securely initiate account connections for your users, you'll need generate a short-lived token for your users and use that in the [account connection flow](#connect-your-users-account). See [the docs on Connect tokens](/connect/tokens) for a general overview of why we need to create tokens and scope them to end users.

In the Next.js example here, we're running [Next server components](https://nextjs.org/docs/app/building-your-application/rendering/server-components) in `app/server.ts`. We call the `serverConnectTokenCreate` method from the frontend to retrieve a token **for a specific user**.

```typescript
import { serverConnectTokenCreate } from "./server"

const { token, expires_at } = await serverConnectTokenCreate({
  external_user_id: externalUserId  // The end user's ID in your system
});
```

If you're using a different server / API framework, you'll need to make secure calls to that API to create a new token for your users.

Once you have a token, return it to your frontend to start the account connection flow for the user, or redirect them to a Pipedream-hosted URL with [Connect Link](#or-use-connect-link).

<Callout type="info">
Refer to the API docs for [full set of parameters you can pass](/connect/api#create-a-new-token) in the `ConnectTokenCreate` call.
</Callout>

### Connect your user's account

To connect a third-party account for a user, you have two options:

1. [Use the Pipedream SDK](#use-the-pipedream-sdk-in-your-frontend) in your frontend
2. [Use Connect Link](#or-use-connect-link) to deliver a hosted URL to your user

#### Use the Pipedream SDK in your frontend

Use this method when you want to handle the account connection flow yourself, in your app. For example, you might want to show a **Connect Slack** button in your app that triggers the account connection flow.

First, install the [Pipedream SDK](https://www.npmjs.com/package/@pipedream/sdk) in your frontend:

```bash
npm i --save @pipedream/sdk
```

When the user connects an account in your product, [pass the token from your backend](#generate-a-short-lived-token) and call `connectAccount`. This opens a Pipedream iFrame that guides the user through the account connection.

In our example, `app/page.tsx` calls the `connectAccount` method from the Pipedream SDK when the user clicks the **Connect your account** button.

<br />
<Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1733865948/Google_Chrome_-_Pipedream_Connect_Demo_2024-12-10_at_1.23.47_PM_mwxfzh.png" alt="Connect your account button" width={650} height={300} />

```typescript
import { createFrontendClient } from "@pipedream/sdk/browser"

export default function Home() {
  const pd = createFrontendClient()
  function connectAccount() {
    pd.connectAccount({
      app: appSlug, // Pass the app name slug of the app you want to integrate
      oauthAppId: appId, // For OAuth apps, pass the OAuth app ID; omit this param to use Pipedream's OAuth client or for key-based apps
      token: "YOUR_TOKEN", // The token you received from your server above
      onSuccess: ({ id: accountId }) => {
        console.log(`Account successfully connected: ${accountId}`)
      }
    })
  }

  return (
    <main>
      <button onClick={connectAccount}>Connect your account</button>
    </main>
  )
}
```

Press that button to connect an account for the app you configured.

#### Or use Connect Link

Use this option when you can't execute JavaScript or open an iFrame in your environment (e.g. mobile apps), or when you want to offload the account connection flow to Pipedream and avoid frontend work. You can also send these links via email or SMS.

The Connect Link opens a Pipedream-hosted page, guiding users through the account connection process. The URL is specific to the user and expires after 4 hours.

1. First, [generate a token](#generate-a-short-lived-token) for your users.
2. Extract the `connect_link_url` from the token response.
3. Before returning the URL to your user, add an `app` parameter to the end of the query string:

```
https://pipedream.com/_static/connect.html?token={token}&connectLink=true&app={appSlug}&oauthAppId={oauthAppId}
```

4. Redirect your users to this URL, or send it to them via email, SMS, and more.

### Make authenticated requests

Now that your users have connected an account, you can use their auth in one of a few ways:

1. [Retrieve their credentials from the REST API](/connect/api#accounts) to use in your backend application
2. [Use Pipedream's visual workflow builder](/connect/workflows) to define complex logic to run on behalf of your users
3. [Embed Pipedream components directly in your app](/connect/components) to run actions and triggers on their behalf

### Deploy your app to production

- Test end to end in [development](/connect/environments)
- Ship to production!

</Steps>