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 slug
oauth_app_id - The OAuth app ID, if you're connecting an OAuth app — keep this in config / a DB, pass here
external_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. 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: "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 — the oauth_app_id for OAuth apps or name slug for key-based apps
include_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: "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 retrieve
include_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: "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 system
include_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 be oauth_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

Quickstart Overview

Connect API & SDK Reference

REST API Base URL

Installing the TypeScript SDK

npm

<script> tag

Authentication

TypeScript SDK (Server)

TypeScript SDK (Browser)

REST API

External users

Rate limits

API Reference

Tokens

Create a new token

Parameters

Examples

Accounts

List all accounts

Parameters

Examples

Example response

List all accounts for an app

Parameters

Examples

Example response

Retrieve account details by ID

Parameters

Examples

Example response (without account credentials)

Example Response (with include_credentials=1)

Retrieve accounts for an external user

Parameters

Examples

Example response (without account credentials)

Example Response (with include_credentials=1)

Delete connected account

Parameters

Examples

Response

Delete all connected accounts for an app

Parameters

Examples

Response

Delete an end user

Parameters

Examples

Response

`<script>` tag

Example Response (with `include_credentials=1`)

Example Response (with `include_credentials=1`)