Quickstart
Pipedream Connect is the easiest way for your users to connect to over 2,200+ APIs, right in your product. You can build in-app messaging, CRM syncs, AI-driven products, and much more, all in a few minutes.
If you prefer videos to text, this demo walks through this quickstart:
Visual overview
Here's a high-level overview of how Connect works with your app:
And here's the technical flow between your frontend, backend, and Pipedream's API, described step-by-step below:
Choose the apps you want to integrate
There are two types of apps in Pipedream:
- Key-based: These apps require static credentials, like API keys. Pipedream stores these credentials securely and exposes them via API.
- 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:
- Visit https://pipedream.com/apps
- Search and select the app you want to integrate
- 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
- Open an existing Pipedream project or create a new one at https://pipedream.com/projects.
- Visit the Connect tab, then select Configuration.
- 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:
- 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.
- 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
Why do I need to talk to the Pipedream API from my server?
You need to secure specific operations, for example:
- You need to initiate the account connection flow for your end users. In Pipedream Connect, you exchange your project keys for a short-lived token that allows a specific user to connect a specific app, and return that token to your frontend. If you expose your Pipedream project keys directly to the frontend, anyone could initiate the account connection flow for any user, and you'd be charged for those accounts.
- You need to retrieve account credentials for your end users. Again, this should happen securely on your server, not in the frontend, to protect your users' data.
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!