Quickstart

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. 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 or redirect your users to a Pipedream-hosted URL to start the account connection flow.

We'll walk through these steps below, using an example Next.js app. To follow along, clone the repo and follow the instructions in the app's README. That will run the app on localhost:3000.

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

cp .env.example .env.local

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

# 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.
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 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. See the docs on 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 in app/server.ts. We call the serverConnectTokenCreate method from the frontend to retrieve a token for a specific user.

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.

Connect a user's account

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

1. Use the Pipedream SDK in your frontend
2. 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 in your frontend:

npm i --save @pipedream/sdk

When the user connects an account in your product, pass the token from your backend 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.

import { createFrontendClient } from "@pipedream/sdk"
 
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.

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 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.

Retrieve the credentials from the backend

Once your user connects an account, you can retrieve their credentials from your backend.

This example shows you how to fetch credentials by your end user's external_user_id. You can also fetch all connected accounts for a specific app, or a specific user — see the Connect API reference.

import {
  createBackendClient,
} from "@pipedream/sdk";
 
const pd = createBackendClient({
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});
 
async function getUserAccounts(external_user_id: string, include_credentials: boolean = false) {
  await pd.getAccounts({
    external_user_id,
    include_credentials, // set to true to include credentials
  })
 
  // Parse and return the data you need. These may contain credentials, 
  // which you should never return to the client
}

Deploy your app to production

• Now that you've successfully connected an account and retrieved the credentials, you're almost done!
• Learn about development environments and using OAuth clients to deploy your app to production.