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.

REST API Base URL

Pipedream Connect resources are scoped to projects, so you'll need to pass the project's ID as a part of the base URL:

https://api.pipedream.com/v1/connect/{project_id}

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

See the REST API Authentication docs.

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.

Create a Pipedream OAuth client and instantiate the SDK with your client ID and secret:

import { createBackendClient } from "@pipedream/sdk";
 
// These secrets should be saved securely and passed to your environment
const pd = createBackendClient({
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});
 
// 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:

import { createFrontendClient } from "@pipedream/sdk"
// Example from our Next.js app
import { serverConnectTokenCreate } from "./server"
 
const { token, expires_at } = await serverConnectTokenCreate({
  external_user_id: externalUserId  // The end user's ID in your system
});
 
export default function Home() {
  const pd = createFrontendClient()
  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, // 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>
  )
}

Environment

Some API endpoints accept an environment parameter. This lets you specify the environment (production or development) where resources will live in your project.

You can set the environment when you create the SDK client:

import { createBackendClient } from "@pipedream/sdk";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});

or pass the X-PD-Environment header in HTTP requests:

curl -X POST https://api.pipedream.com/v1/connect/{project_id}/tokens \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: development" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "your-external-user-id"
  }'

External users

When you use the Connect API, you'll pass an external_user_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 User IDs are limited to 250 characters.

Rate limits

API Endpoint	Rate Limit
`POST /tokens`	100 requests per minute per `external_user_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

Invoke workflows

You can use the SDK to invoke workflows on behalf of any end user. Write one workflow, run it for all of your users.

import { createBackendClient, HTTPAuthType } from "@pipedream/sdk";
 
// These secrets should be saved securely and passed to your environment
const pd = createBackendClient({
  credentials: {
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
  },
});
 
await pd.invokeWorkflowForExternalUser(
  "enabc123", // pass the endpoint ID or full URL here
  "external_user_id", // The end user's ID in your system
  {
    method: "POST",
    body: {
      key: "value",
    }
  },
  HTTPAuthType.OAuth // Will automatically send the Authorization header with a fresh token
)

See the workflow invocation docs for more details.

Tokens

Your app will initiate the account connection flow for your end users in your frontend. To securely scope connection to a specific end user, on your server, you retrieve a short-lived token for that user, and return that token to your frontend.

See the Connect tokens docs for more information.

Create a new token

POST /{project_id}/tokens

Path parameters

project_id string

The project's ID

Body parameters

external_user_id string

The ID of your end user. Use whatever ID uniquely identifies the user in your system.

success_redirect_uri string (optional)

When using Connect Link, you can optionally redirect your end user to the success_redirect_uri on successful completion of the auth flow.

error_redirect_uri string (optional)

When using Connect Link, you can optionally redirect your end user to the error_redirect_uri on any errors in the auth flow. This lets you handle errors in whatever way you want in your own app.

webhook_uri string (optional)

Pipedream will send events on successful auth, or any errors, to this URL via webhook. See the webhooks docs for more information.

environment_name string (optional)

Specify the environment (production or development) to use for the account connection flow. Defaults to production.

Examples

To create a short-lived token via TypeScript / JavaScript SDK, you'll need to create a Pipedream API client and call the createConnectToken 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.

import {
  createBackendClient,
  type ConnectAPIResponse, 
  type ConnectTokenCreateOpts, 
  type ConnectTokenResponse,
} from "@pipedream/sdk";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});
 
const { token, expires_at } = await pd.createConnectToken({
  project_id: "your-project-id",
  external_user_id: "your-external-user-id"  // The end user's ID in your system
});

Accounts

List all accounts

List all connected accounts for all end users within a project.

GET /{project_id}/accounts/

Path parameters

project_id string

The project's ID

Query parameters

app string (optional)

The ID or name slug the app you'd like to retrieve. For example, Slack's unique app ID is app_OkrhR1, and its name slug is slack.

You can find the app's ID in the response from the List apps endpoint, and the name slug under the Authentication section of any app page.

oauth_app_id string (optional)

The ID of the custom OAuth app you'd like to retrieve accounts for.

external_user_id string (optional)

The external user ID in your system that you want to retrieve accounts for.

include_credentials boolean (optional)

Pass include_credentials=true as a query-string parameter to include the account credentials in the response

Examples

import {
  createBackendClient,
} from "@pipedream/sdk";
 
const pd = createBackendClient({
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});
 
const accounts = await pd.getAccounts({
  include_credentials: true, // set to true to include credentials
});
 
// Parse and return the data you need. These may contain credentials, 
// which you should never return to the client

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"
      }
    ]
  }
}

Retrieve account details by ID

Retrieve the account details for a specific account based on the account ID

GET /{project_id}/accounts/{account_id}

Path parameters

project_id string

The project's ID

account_id string

The ID of the account you want to retrieve

Parameters

include_credentials boolean (optional)

Pass include_credentials=true as a query-string parameter to include the account credentials in the response.

Examples

import {
  createBackendClient,
} from "@pipedream/sdk";
 
const pd = createBackendClient({
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});
 
const account = await pd.getAccount(accountId, {
  include_credentials: true, // set to true 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)

{
  "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=true`)

{
  "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"
  }
}

Delete connected account

Delete a specific connected account for an end user

DELETE /{project_id}/accounts/{account_id}

Path parameters

project_id string

The project's ID

account_id string

Examples

import {
  createBackendClient,
} from "@pipedream/sdk";
 
const pd = createBackendClient({
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});
 
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 /{project_id}/apps/{app_id}/accounts

Path parameters

project_id string

The project's ID

app_id string

The app ID for which you want to delete all connected accounts. app_id can be oauth_app_id for OAuth apps or name slug for key-based apps.

Examples

import {
  createBackendClient,
} from "@pipedream/sdk";
 
const pd = createBackendClient({
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});
 
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 /{project_id}/users/{external_user_id}

Path parameters

project_id string

The project's ID

external_user_id string

The external user ID in your system

Examples

import {
  createBackendClient,
} from "@pipedream/sdk";
 
const pd = createBackendClient({
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});
 
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

Projects

Retrieve project info

Retrieve the configuration for a specific project

GET /{project_id}/info

Path parameters

project_id string

The project's ID

Examples

import { createBackendClient } from "@pipedream/sdk";
 
const pd = createBackendClient({
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});
 
const info = await pd.getProjectInfo({
  project_id: "your-project-id",
});

Quickstart Connect Tokens

Connect API & SDK Reference

REST API Base URL

Installing the TypeScript SDK

npm

<script> tag

Authentication

TypeScript SDK (Server)

TypeScript SDK (Browser)

Environment

External users

Rate limits

API Reference

Invoke workflows

Tokens

Create a new token

Path parameters

Body parameters

Examples

Accounts

List all accounts

Path parameters

Query parameters

Examples

Example response

Retrieve account details by ID

Path parameters

Parameters

Examples

Example response (without account credentials)

Example Response (with include_credentials=true)

Delete connected account

Path parameters

Examples

Response

Delete all connected accounts for an app

Path parameters

Examples

Response

Delete an end user

Path parameters

Examples

Response

Projects

Retrieve project info

Path parameters

Examples

`<script>` tag

Example Response (with `include_credentials=true`)