Quickstart

Get your project keys

1. Open an existing Pipedream project or create a new one at https://pipedream.com/projects.
2. From within the Connect tab in your project, select Configuration.
3. Find your project's Public Key and Secret Key.

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

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_PROJECT_PUBLIC_KEY=pub_abc123
PIPEDREAM_PROJECT_SECRET_KEY=sec_abc123

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

Connect to the Pipedream API from your server and create a token

In this Next.js example, we're running Node.js code on our server, via Next server components, so we'll use the Pipedream SDK. Additional examples in Python, Ruby, and other languages are noted below.

To install the Pipedream SDK in your own project, run:

npm i --save @pipedream/sdk

To create a short-lived token via TypeScript / JavaScript SDK, you'll need to create a Pipedream API client and call the connectTokenCreate method. In our example app, this code is in app/server.ts.

In other languages, you'll need to make an HTTP POST request to the /v1/connect/tokens endpoint to create a token, then return the token to your frontend. Click into other tabs to see examples in additional languages.

"use server";
 
import {
  createClient,
  type ConnectAPIResponse, 
  type ConnectTokenCreateOpts, 
  type ConnectTokenResponse,
} from "@pipedream/sdk";
 
const pd = createClient({
  publicKey: process.env.PIPEDREAM_PROJECT_PUBLIC_KEY,
  secretKey: process.env.PIPEDREAM_PROJECT_SECRET_KEY,
});
 
export async function serverConnectTokenCreate(opts: ConnectTokenCreateOpts): Promise<ConnectAPIResponse<ConnectTokenResponse>> {
  return pd.connectTokenCreate(opts);
}

In our Next.js app, 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. For example, you might validate a user's session, then call the Pipedream API to create a new token for that user.

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 (see above).

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.

// Note that we import the browser-specific SDK client here
import { createClient } from "@pipedream/sdk/browser"
 
export default function Home() {
  const pd = createClient()
  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 the user connects an account, you can retrieve their credentials from your backend with your project keys.

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

import {
  createClient,
} from "@pipedream/sdk";
 
const pd = createClient({
  publicKey: PIPEDREAM_PROJECT_PUBLIC_KEY,
  secretKey: PIPEDREAM_PROJECT_SECRET_KEY,
});
 
export async function getUserAccounts(externalId: string, include_credentials: number = 0) {
  await pd.getAccountsByExternalId(externalId, {
    include_credentials, // set to 1 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.