Skip to main content
The Pipedream Connect API supports two authentication methods:
  1. OAuth access tokens: Server-side authentication using client credentials
  2. Connect tokens: Client-side authentication using short-lived tokens scoped to individual end users
Both approaches support scopes to limit access to specific operations.

​
OAuth Access Tokens

OAuth access tokens are used for server-side API requests. They’re generated using the client credentials flow and expire after 1 hour. Why OAuth? ✅ OAuth clients are tied to the Pipedream workspace and administered by workspace admins
✅ Tokens are short-lived
✅ OAuth access tokens support scopes, limiting access to specific operations
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

  1. Visit the API settings for your Pipedream workspace
  2. Click the New OAuth Client button
  3. Name your client and click Create
  4. Copy the client ID and secret (the secret will not be accessible again)

​
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. Pipedream offers TypeScript, Python, and Java SDKs, which abstract the process of generating and refreshing fresh access tokens. 
import { PipedreamClient } from "@pipedream/sdk";

const client = new PipedreamClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  projectEnvironment: "YOUR_PROJECT_ENVIRONMENT",
  projectId: "YOUR_PROJECT_ID",
  // Optional: specify scopes (defaults to "*")
  scope: "connect:accounts:read connect:accounts:write"
});
await client.accounts.retrieve("account_id");
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>",
    "scope": "connect:accounts:read connect:accounts:write"
  }'
The scope parameter is optional and accepts a space-separated list of scopes. If omitted, the token defaults to * (full access). Access tokens expire after 1 hour. Store access tokens securely in your server.

​
OAuth scopes

OAuth access tokens support scopes to limit access to specific operations. When creating an access token, you can optionally specify a space-separated list of scopes. If no scope is specified, the token defaults to * (full access). Available scopes:
ScopeDescription
*Full access to every OAuth-protected endpoint
connect:*Full access to all Connect API endpoints (components, projects, triggers, accounts, etc.)
connect:actions:*Full access to Connect actions
connect:triggers:*Full access to Connect triggers
connect:accounts:readList and fetch Connect accounts for an external user
connect:accounts:writeCreate or remove Connect accounts
connect:deployed_triggers:readRead deployed triggers and related data like events, pipelines and webhooks
connect:deployed_triggers:writeModify or delete deployed triggers
connect:usage:readList Connect usage records for a time window
connect:users:readList and fetch external users
connect:users:writeDelete external users
connect:tokens:createCreate Connect session tokens
connect:proxyInvoke the Connect proxy
connect:workflow:invokeInvoke Connect workflows on behalf of a user

​
Revoking a client secret

  1. Visit your workspace’s API settings
  2. Click the … button to the right of the OAuth client whose secret you want to revoke, then click Rotate client secret
  3. 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.

​
Connect Tokens

Connect tokens are short-lived tokens that enable you to securely make client-side requests on behalf of end users. They’re created server-side and passed to your frontend to authenticate requests.

​
Creating a Connect token

Use the Create Connect token endpoint to generate a token for an external user: 
import { PipedreamClient } from "@pipedream/sdk";

const client = new PipedreamClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  projectEnvironment: "YOUR_PROJECT_ENVIRONMENT",
  projectId: "YOUR_PROJECT_ID"
});

const { token, expires_at } = await client.createConnectToken({
  externalUserId: "user-123",
  // Optional: customize TTL (defaults to 4 hours)
  expiresIn: 3600, // 1 hour
  // Optional: restrict scopes (defaults to "connect:*")
  scope: "connect:accounts:read connect:accounts:write"
});

​
Connect token TTL

Connect tokens have a customizable time-to-live (TTL):
  • Minimum: 1 second
  • Maximum: 14,400 seconds (4 hours)
  • Default: 14,400 seconds (4 hours)
Specify the TTL using the expires_in parameter (in seconds) when creating a token.

​
Connect token scopes

Connect tokens support the same scopes as OAuth access tokens. When creating a Connect token, you can optionally specify a space-separated list of scopes. If no scope is specified, the token defaults to connect:* (full access to all Connect API endpoints). Available scopes:
ScopeDescription
connect:*Full access to all Connect API endpoints (components, projects, triggers, accounts, etc.)
connect:actions:*Full access to Connect actions
connect:triggers:*Full access to Connect triggers
connect:accounts:readList and fetch Connect accounts for an external user
connect:accounts:writeCreate or remove Connect accounts
connect:deployed_triggers:readRead deployed triggers and related data like events, pipelines and webhooks
connect:deployed_triggers:writeModify or delete deployed triggers
connect:usage:readList Connect usage records for a time window
connect:users:readList and fetch external users
connect:users:writeDelete external users
connect:tokens:createCreate Connect session tokens
connect:proxyInvoke the Connect proxy
connect:workflow:invokeInvoke Connect workflows on behalf of a user
Connect tokens cannot be granted the * scope. The maximum scope available is connect:*.