Connect API & SDK Reference
Pipedream provides a TypeScript SDK and a REST API to interact with the Connect service. You'll find examples using the SDK and the REST API in multiple languages below.
Note that both the Base URL and authentication method for the Connect REST API are different from the rest of Pipedream's REST API.
REST API Base URL
https://api.pipedream.com/v1/connect
Installing the TypeScript SDK
Pipedream's SDK will work in any browser or server that can run JavaScript.
npm
To install the SDK from npm, run:
npm i --save @pipedream/sdk
<script>
tag
You can also load the client-side SDK via <script>
tag. You can run the latest version:
<script src="https://unpkg.com/@pipedream/sdk/dist/browser/index.js"></script>
or a specific version:
<script src="https://unpkg.com/@pipedream/sdk@0.0.13/dist/browser/index.js"></script>
Authentication
TypeScript SDK (Server)
Most of your interactions with the Connect API will happen on the server, to protect API requests and user credentials. You'll use the SDK in your frontend to let users connect accounts. Once connected, you'll use the SDK on the server to retrieve credentials, invoke workflows on their behalf, and more.
Find your project keys and instantiate the SDK client:
import { createClient } from "@pipedream/sdk";
// These secrets should be saved securely and passed to your environment
const pd = createClient({
publicKey: "YOUR_PUBLIC_KEY",
secretKey: "YOUR_SECRET_KEY",
});
// The `pd` client provides methods to interact with the Connect API — see below
TypeScript SDK (Browser)
You'll primarily use the browser SDK to let your users securely connect apps from your frontend. Here, you
- Create a short-lived token on your server
- Initiate auth with that token to securely connect an account for a specific user
Here's a Next.js example from our quickstart:
// Note that we import the browser-specific SDK client here
import { createClient } from "@pipedream/sdk/browser"
// Example from our Next.js app
import { serverConnectTokenCreate } from "./server"
const { token, expires_at } = await serverConnectTokenCreate({
app_slug: appSlug, // The app's name slug — see the quickstart
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
});
export default function Home() {
const pd = createClient({})
function connectAccount() {
pd.connectAccount({
app: appSlug,
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>
)
}
REST API
You authenticate to the Connect API using Basic Auth. Send your project public key as the username and the project secret key as the password. When you make API requests, pass an
Authorization
header of the following format:
Authorization: Basic base_64(public_key:secret_key)
Clients like cURL
will often make this easy. For example, here's how you list all accounts on a project:
curl 'https://api.pipedream.com/v1/connect/accounts' -u public_key:secret_key
External users
When you use the Connect API, you'll pass an external_id
parameter when initiating account connections and retrieving credentials. This is your user's ID, in your system — whatever you use to uniquely identify them.
Pipedream associates this ID with user accounts, so you can retrieve credentials for a specific user, and invoke workflows on their behalf.
External IDs are limited to 250 characters.
Rate limits
API Endpoint | Rate Limit |
---|---|
POST /tokens | 100 requests per minute per external_id |
GET */accounts/* | The sum of requests across all */accounts/* endpoints must not exceed 100 requests per minute. This includes requests to /accounts , /apps/:app_id/accounts , /accounts/:account_id , and more — any request for account metadata and credentials is counted towards this total. |
If you need higher rate limits, please reach out.
API Reference
Tokens
Your app will initiate the account connection flow for your end users in your frontend. But you can't expose your project keys in the client, since they'd be accessible to anyone. Instead, on your server, 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.
Create a new token
POST /tokens
Parameters
app_slug
- The app's name slugoauth_app_id
- The OAuth app ID, if you're connecting an OAuth app — keep this in config / a DB, pass hereexternal_id
- The external user ID in your system
Examples
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 /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);
}
const { token, expires_at } = await serverConnectTokenCreate({
app_slug: appSlug, // The app's name slug
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
});
Accounts
List all accounts
List all connected accounts for all end users within your project
This endpoint is not currently paginated, so we'll attempt to return all connected accounts for all users within your project. We intend to add pagination soon.
GET /accounts/
Parameters
include_credentials
— Optional. Passinclude_credentials=1
as a query-string parameter to include the account credentials in the response
Examples
import {
createClient,
} from "@pipedream/sdk";
const pd = createClient({
publicKey: "YOUR_PUBLIC_KEY",
secretKey: "YOUR_SECRET_KEY",
});
export async function getAccounts(include_credentials: number = 0) {
const accounts = await pd.getAccounts({
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
return accounts;
}
Example response
{
"data": {
"accounts": [
{
"id": "apn_XehyZPr",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "app_OkrhR1",
"name": "Slack"
},
"created_at": "2024-07-30T22:52:48.000Z",
"updated_at": "2024-08-01T03:44:17.000Z"
},
{
"id": "apn_b6h9QDK",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "app_OrZhaO",
"name": "GitHub"
},
"created_at": "2024-07-31T02:49:18.000Z",
"updated_at": "2024-08-01T03:58:17.000Z"
},
{
"id": "apn_0WhJYxv",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "app_OrZhaO",
"name": "GitHub"
},
"created_at": "2024-07-31T20:28:16.000Z",
"updated_at": "2024-08-01T03:47:30.000Z"
},
{
"id": "apn_kVh9PJx",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "app_OrZhaO",
"name": "GitHub"
},
"created_at": "2024-07-31T21:17:03.000Z",
"updated_at": "2024-08-01T03:43:23.000Z"
},
{
"id": "apn_WYhMlrz",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "app_XBxhAl",
"name": "Airtable"
},
"created_at": "2024-08-01T04:04:03.000Z",
"updated_at": "2024-08-01T04:04:03.000Z"
}
]
}
}
List all accounts for an app
GET /apps/:app_id/accounts
Parameters
app_id
— theoauth_app_id
for OAuth apps or name slug for key-based appsinclude_credentials
— Optional. Passinclude_credentials=1
as a query-string parameter to include the account credentials in the response
Examples
import {
createClient,
} from "@pipedream/sdk";
const pd = createClient({
publicKey: "YOUR_PUBLIC_KEY",
secretKey: "YOUR_SECRET_KEY",
});
export async function getAccountsByApp(appId: string, include_credentials: number = 0) {
const accounts = await pd.getAccountsByApp(appId, {
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
return accounts;
}
Example response
[
{
"id": "apn_WYhMlrz",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "oa_aw4ib2",
"name_slug": "airtable_oauth",
"name": "Airtable",
"auth_type": "oauth",
"description": "Airtable is a low-code platform to build next-gen apps. Move beyond rigid tools, operationalize your critical data, and reimagine workflows with AI.",
"img_src": "https://assets.pipedream.net/s.v0/app_XBxhAl/logo/orig",
"custom_fields_json": "[]",
"categories": ["Productivity"]
},
"created_at": "2024-08-01T04:04:03.000Z",
"updated_at": "2024-08-01T04:04:03.000Z"
}
]
Retrieve account details by ID
Retrieve the account details for a specific account based on the account ID
GET /accounts/:account_id
Parameters
account_id
— the ID of the account you want to retrieveinclude_credentials
— Optional. Passinclude_credentials=1
as a query-string parameter to include the account credentials in the response
Examples
import {
createClient,
} from "@pipedream/sdk";
const pd = createClient({
publicKey: "YOUR_PUBLIC_KEY",
secretKey: "YOUR_SECRET_KEY",
});
export async function getAccount(accountId: string, include_credentials: number = 0) {
const account = await pd.getAccount(accountId, {
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
return account;
}
Example response (without account credentials)
{
"data": {
"id": "apn_WYhMlrz",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "oa_aw4ib2",
"name_slug": "airtable_oauth",
"name": "Airtable",
"auth_type": "oauth",
"description": "Airtable is a low-code platform to build next-gen apps. Move beyond rigid tools, operationalize your critical data, and reimagine workflows with AI.",
"img_src": "https://assets.pipedream.net/s.v0/app_XBxhAl/logo/orig",
"custom_fields_json": "[]",
"categories": ["Productivity"]
},
"created_at": "2024-08-01T04:04:03.000Z",
"updated_at": "2024-08-01T04:04:03.000Z"
}
}
Example Response (with include_credentials=1
)
{
"data": {
"id": "apn_WYhMlrz",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "app_XBxhAl",
"name": "Airtable"
},
"created_at": "2024-08-01T04:04:03.000Z",
"updated_at": "2024-08-01T04:04:03.000Z",
"credentials": {
"oauth_client_id": "dd7a26ca-ba11-4f80-8667-xxxxxxxx",
"oauth_access_token": "oaaLa2Ob1umiregWa.v1.xxxxxxxx.xxxxxxxx",
"oauth_refresh_token": "oaaLa2Ob1umiregWa.v1.refresh.xxxxxxxx",
"oauth_uid": "usrnbIhrxxxxxxxx"
},
"expires_at": "2024-08-01T05:04:03.000Z",
"project_id": 279440,
"user_id": "danny",
"error": null,
"last_refreshed_at": null,
"next_refresh_at": "2024-08-01T04:17:33.000Z"
}
}
Retrieve accounts for an external user
Retrieve the account details for a specific account based on the external user ID
GET /users/:external_id/accounts
Parameters
external_id
— The external user ID in your systeminclude_credentials
— Optional. Pass?include_credentials=1
as a query-string parameter to include the account credentials in the response
Examples
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
}
Example response (without account credentials)
[
{
"id": "apn_WYhM5ov",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "oa_aw4ib2",
"name_slug": "airtable_oauth",
"name": "Airtable",
"auth_type": "oauth",
"description": "Airtable is a low-code platform to build next-gen apps. Move beyond rigid tools, operationalize your critical data, and reimagine workflows with AI.",
"img_src": "https://assets.pipedream.net/s.v0/app_XBxhAl/logo/orig",
"custom_fields_json": "[]",
"categories": [
"Productivity"
]
},
"created_at": "2024-08-06T21:51:30.000Z",
"updated_at": "2024-08-06T21:51:30.000Z",
"expires_at": "2024-08-06T22:51:30.000Z",
"error": null,
"last_refreshed_at": null,
"next_refresh_at": "2024-08-06T22:04:41.000Z"
},
{
"id": "apn_KAh7JwW",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "oa_aPXiQd",
"name_slug": "github",
"name": "GitHub",
"auth_type": "oauth",
"description": "Where the world builds software. Millions of developers and companies build, ship, and maintain their software on GitHub—the largest and most advanced development platform in the world.",
"img_src": "https://assets.pipedream.net/s.v0/app_OrZhaO/logo/orig",
"custom_fields_json": "[]",
"categories": [
"Developer Tools"
]
},
"created_at": "2024-08-06T21:53:05.000Z",
"updated_at": "2024-08-06T21:53:05.000Z",
"expires_at": null,
"error": null,
"last_refreshed_at": null,
"next_refresh_at": "2024-08-06T22:50:01.000Z"
}
]
Example Response (with include_credentials=1
)
[
{
"id": "apn_WYhM5ov",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "oa_aw4ib2",
"name_slug": "airtable_oauth",
"name": "Airtable",
"auth_type": "oauth",
"description": "Airtable is a low-code platform to build next-gen apps. Move beyond rigid tools, operationalize your critical data, and reimagine workflows with AI.",
"img_src": "https://assets.pipedream.net/s.v0/app_XBxhAl/logo/orig",
"custom_fields_json": "[]",
"categories": [
"Productivity"
]
},
"created_at": "2024-08-06T21:51:30.000Z",
"updated_at": "2024-08-06T21:51:30.000Z",
"credentials": {
"oauth_client_id": "dd7a26ca-ba11-4f80-8667-xxxxxxxx",
"oauth_access_token": "oaaLa2Ob1umiregWa.v1.xxxxxxxx.xxxxxxxx",
"oauth_refresh_token": "oaaLa2Ob1umiregWa.v1.refresh.xxxxxxxx",
"oauth_uid": "usrnbIhrxxxxxxxx"
},
"expires_at": "2024-08-06T22:51:30.000Z",
"error": null,
"last_refreshed_at": null,
"next_refresh_at": "2024-08-06T22:04:41.000Z"
},
{
"id": "apn_KAh7JwW",
"name": null,
"external_id": "user-abc-123",
"healthy": true,
"dead": false,
"app": {
"id": "oa_aPXiQd",
"name_slug": "github",
"name": "GitHub",
"auth_type": "oauth",
"description": "Where the world builds software. Millions of developers and companies build, ship, and maintain their software on GitHub—the largest and most advanced development platform in the world.",
"img_src": "https://assets.pipedream.net/s.v0/app_OrZhaO/logo/orig",
"custom_fields_json": "[]",
"categories": [
"Developer Tools"
]
},
"created_at": "2024-08-06T21:53:05.000Z",
"updated_at": "2024-08-06T21:53:05.000Z",
"credentials": {
"oauth_client_id": "57dc28xxxxxxxxxxxxx",
"oauth_access_token": "gho_xxxxxxxxxxxxxxxxxx",
"oauth_uid": "104484339"
},
"expires_at": null,
"error": null,
"last_refreshed_at": null,
"next_refresh_at": "2024-08-06T22:50:01.000Z"
}
]
Delete connected account
Delete a specific connected account for an end user
DELETE /v1/connect/accounts/:account_id
Parameters
account_id
is the ID of the account you want to retrieve
Examples
import {
createClient,
} from "@pipedream/sdk";
const pd = createClient({
publicKey: "YOUR_PUBLIC_KEY",
secretKey: "YOUR_SECRET_KEY",
});
export async function deleteAccount(accountId: string) {
await pd.deleteAccount(accountId);
// You can return a message or handle any post-deletion logic here.
}
Response
Pipedream returns a 204 No Content
response on successful account deletion
Delete all connected accounts for an app
Delete all connected accounts for a specific app
DELETE /apps/:app_id/accounts
Parameters
app_id
can beoauth_app_id
for OAuth apps or name slug for key-based apps
Examples
import {
createClient,
} from "@pipedream/sdk";
const pd = createClient({
publicKey: "YOUR_PUBLIC_KEY",
secretKey: "YOUR_SECRET_KEY",
});
export async function deleteAccountsByApp(appId: string) {
await pd.deleteAccountsByApp(appId);
// You can return a message or handle any post-deletion logic here.
}
Response
Pipedream returns a 204 No Content
response on successful account deletion
Delete an end user
Delete an end user and all their connected accounts
DELETE /users/:external_id
Parameters
external_id
— The external user ID in your system
Examples
import {
createClient,
} from "@pipedream/sdk";
const pd = createClient({
publicKey: "YOUR_PUBLIC_KEY",
secretKey: "YOUR_SECRET_KEY",
});
export async function deleteExternalUser(externalId: string) {
await pd.deleteExternalUser(externalId);
console.log("All accounts associated with the external ID have been deleted.");
}
Response
Pipedream returns a 204 No Content
response on successful account deletion