Authentication

The Pipedream API supports two methods of authentication: OAuth and User API keys.

We recommend OAuth for a few reasons:

✅ OAuth clients are tied to the workspace, administered by workspace admins
✅ Tokens are short-lived
✅ OAuth clients support scopes, limiting access to specific operations (coming soon!)
✅ Limit access to specific Pipedream projects (coming soon!)

When testing the API or using the CLI, you can use your user API key. This key is tied to your user account and provides full access to any resources your user has access to, across workspaces.

OAuth

Workspace administrators can create OAuth clients in your workspace's API settings.

Since API requests are meant to be made server-side, and since grants are not tied to individual end users, all OAuth clients are Client Credentials applications.

Creating an OAuth client

Visit the API settings for your workspace.
Click the New OAuth Client button.
Name your client and click Create.
Copy the client secret. It will not be accessible again. Click Close.
Copy the client ID from the list.

How to get an access token

In the client credentials model, you exchange your OAuth client ID and secret for an access token. Then you use the access token to make API requests.

If you're running a server that executes JavaScript, we recommend using the Pipedream SDK, which automatically refreshes tokens for you.

import { createBackendClient } 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",
  },
});
 
// Use the SDK's helper methods to make requests
const accounts = await pd.getAccounts({ include_credentials: 1 });
 
// Or make any Pipedream API request with the fresh token
const accounts = await pd.makeRequest("/accounts", {
  method: "GET"
  headers: {
    "Authorization": await this.oauthAuthorizationHeader(), // Automatically uses a fresh token
  },
  params: {
    include_credentials: 1,
  }
});

You can also manage this token refresh process yourself, using the /oauth/token API endpoint:

curl https://api.pipedream.com/v1/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{ "grant_type": "client_credentials", "client_id": "<client_id>", "client_secret": "<client secret>" }'

Access tokens expire after 1 hour. Store access tokens securely, server-side.

Revoking a client secret

Visit your workspace's API settings.
Click the ... button to the right of the OAuth client whose secret you want to revoke, then click Rotate client secret.
Copy the new client secret. It will not be accessible again.

OAuth security

See the OAuth section of the security docs for more information on how Pipedream secures OAuth credentials.

User API keys

When you sign up for Pipedream, an API key is automatically generated for your user account. You can use this key to authorize requests to the API.

You'll find this API key in your User Settings (My Account -> API Key).

Use user API keys when testing the API or using the CLI. This key is tied to your user account and provides full access to any resources your user has access to, across workspaces.

Revoking your API key

You can revoke your API key in your Account Settings (Settings -> Account). Click on the REVOKE button directly to the right of your API key.

This will revoke your original API key, generating a new one. Any API requests made with the original token will yield a 401 Unauthorized error.

Authorizing API requests

Whether you use OAuth access tokens or user API keys, Pipedream uses Bearer Authentication to authorize your access to the API or SSE event streams. When you make API requests, pass an Authorization header of the following format:

# OAuth access token
Authorization: Bearer <access token>

# User API key
Authorization: Bearer <api key>

For example, here's how you can use cURL to fetch profile information for the authenticated user:

curl 'https://api.pipedream.com/v1/users/me' \
  -H 'Authorization: Bearer <api_key>'

Using the Pipedream CLI

You can link the CLI to your Pipedream account, which will automatically pass your API key in the Authorization header with every API request.

API Reference Example: Create a workflow