Quickstart

Choose the apps you want to integrate

There are two types of apps in Pipedream:

1. Key-based: These apps require static credentials, like API keys. Pipedream stores these credentials securely and exposes them via API.
2. OAuth: These apps require OAuth authorization. Pipedream manages the OAuth flow for these apps, ensuring you always have a fresh access token for requests.

Connecting Key-based apps with the Pipedream API requires only the app's name slug. OAuth apps require you to create your own OAuth client and pass the OAuth app ID, as well.

Find your app's name slug

Typically, the name slug is the name of the app in lowercase, with spaces replaced by underscores. For example, the name slug for the GitHub app is github. The name slug for Google Sheets is google_sheets.

To find the name slug for an app:

1. Visit https://pipedream.com/apps
2. Search and select the app you want to integrate
3. In the Authentication section, copy the Name slug.

Creating a custom OAuth client

First, create an OAuth client for the app you'd like to integrate.

⚠️

Make sure to check the Enable for Pipedream Connect setting in the OAuth client configuration in Pipedream to allow your end users to connect their accounts. By default, OAuth clients are accessible only to members of your Pipedream workspace. Checking this box allows your end users to create accounts for this app, too.

Once that's done, copy the OAuth App ID from the app configuration.

Get your project keys

1. Open an existing Pipedream project or create a new one at https://pipedream.com/projects.
2. Visit the Connect tab, then 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 demo app, or configure your own

You'll need to do two things to integrate Pipedream Connect into 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 the server, you can use the Pipedream SDK.
2. Add the Pipedream SDK to your frontend. This lets you start the account connection flow for your end users.

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:

# Specific to Next.js — see `app/page.tsx` for how these are used
NEXT_PUBLIC_PIPEDREAM_APP_SLUG=github
NEXT_PUBLIC_PIPEDREAM_APP_ID=oa_abc123
 
# 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, and a specific app.

import { serverConnectTokenCreate } from "./server"
 
const { token, expires_at } = await serverConnectTokenCreate({
  app_slug: appSlug,  // The app's name slug, passed from the frontend
  oauth_app_id: oauthAppId,  // The OAuth app ID, if you're connecting an OAuth app — keep this in config / a DB, pass here
  external_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 your account from the frontend

First, install the Pipedream SDK in your frontend:

npm i --save @pipedream/sdk

When the user connects an account in your product, fetch a 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: process.env.NEXT_PUBLIC_PIPEDREAM_APP_SLUG, // From the Next.js example — adjust to pass your own app name slug
      token: "YOUR_TOKEN", // The token you received from your server above
      onSuccess: ({ id: accountId }) => {
        console.log(`Account successfully connected: ${accountId}`)
      }
    })
  }
 
  return (
    <main>
      <button style={{ all: "revert" }} onClick={connectAccount}>Connect your account</button>
    </main>
  )
}

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

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 ready to deploy your app to production!