Authentication

The Pipedream Connect API supports two authentication methods:

OAuth access tokens: Server-side authentication using client credentials
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

Each OAuth client authenticates one of two ways, chosen when you create it in the Pipedream UI:

Client secret: Pipedream generates a secret that your server sends to get access tokens. The steps below create this kind of client.
Public key: your server signs short-lived JWTs with a private key that never leaves your infrastructure, and no shared secret exists. See Private key JWT.

Visit the API settings for your Pipedream workspace
Click the New OAuth Client button
Name your client and click Create
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");

from pipedream import Pipedream

pd = Pipedream(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    project_id="YOUR_PROJECT_ID",
    project_environment="YOUR_PROJECT_ENVIRONMENT",
    # Optional: specify scopes (defaults to "*")
    scope="connect:accounts:read connect:accounts:write"
)
await pd.accounts.retrieve("account_id")

import com.pipedream.api.BaseClient;

BaseClient client = BaseClient
    .builder()
    .clientId("YOUR_CLIENT_ID")
    .clientSecret("YOUR_CLIENT_SECRET")
    .projectId("YOUR_PROJECT_ID")
    .projectEnvironment("YOUR_PROJECT_ENVIRONMENT")
    // Optional: specify scopes (defaults to "*")
    .scope("connect:accounts:read connect:accounts:write")
    .build();

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.

Private key JWT

Instead of a client secret, an OAuth client can authenticate with a public key. You register the public key with Pipedream and keep the private key. To get an access token, your server signs a short-lived JWT (a client assertion) with the private key and sends it to the token endpoint. Pipedream verifies the signature against the registered public key and returns the same access token as for a client secret. This is the private_key_jwt client authentication method defined in RFC 7523, so most OAuth libraries support it. Why use a public key? ✅ No shared secret exists, so nothing reusable is stored by Pipedream or sent over the network
✅ The private key can stay in a key management service or HSM
✅ Keys can be rotated without downtime

A client’s authentication method is fixed when you create it. To move an integration from a client secret to a public key, create a new public-key client and switch your app to its client ID.

Create a public-key client

Generate a key pair

Generate an EC P-256 key pair (recommended) or an RSA key pair. Keep private.pem secret, for example in your secrets manager.

# EC P-256 (signs with ES256)
openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt -out private.pem
openssl ec -in private.pem -pubout -out public.pem

# Or RSA 2048 (signs with RS256)
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.pem
openssl rsa -in private.pem -pubout -out public.pem

Create the client

In the Pipedream UI, open Settings → API (or a project’s Configuration → API) and click New API client. Name the client, choose Public key, paste the contents of public.pem (or the public key as a JWK), and click Create.

Copy the client ID

Copy the Client ID. There is no client secret.

Supported keys

Key type	Signing algorithm (`alg`)	Requirements
EC	`ES256`	Curve P-256
RSA	`RS256`	2048–4096 bits, public exponent 65537

Upload the key as a PEM public key (-----BEGIN PUBLIC KEY-----) or as a single public JWK. Pipedream rejects private keys. If you paste one by mistake, treat it as exposed and generate a new key pair. Each key is assigned a key ID (kid), shown in Manage keys. If you upload a JWK with a kid, Pipedream keeps it; otherwise the key ID is the key’s RFC 7638 thumbprint.

Authenticate with the SDKs

The TypeScript (3.2.0 and later), Python (2.2.0 and later), and Java (2.2.0 and later) SDKs sign client assertions for you. Pass your private key instead of a client secret, and the SDK handles the rest:

it signs a short-lived assertion for every token request
it sets the claims, including the audience
it requests, caches, and refreshes the access token, the same way it does for client secrets

import { PipedreamClient } from "@pipedream/sdk";

const client = new PipedreamClient({
  clientId: "YOUR_CLIENT_ID",
  privateKey: process.env.PIPEDREAM_PRIVATE_KEY, // instead of clientSecret
  projectId: "YOUR_PROJECT_ID",
  projectEnvironment: "YOUR_PROJECT_ENVIRONMENT",
});
await client.accounts.retrieve("account_id");

# pip install "pipedream[private-key]"
import os

from pipedream import Pipedream

pd = Pipedream(
    client_id="YOUR_CLIENT_ID",
    private_key=os.environ["PIPEDREAM_PRIVATE_KEY"],  # instead of client_secret
    project_id="YOUR_PROJECT_ID",
    project_environment="YOUR_PROJECT_ENVIRONMENT",
)
pd.accounts.retrieve("account_id")

import com.pipedream.api.PipedreamClient;

PipedreamClient client = PipedreamClient.builder()
    .clientId("YOUR_CLIENT_ID")
    .privateKey(System.getenv("PIPEDREAM_PRIVATE_KEY")) // instead of clientSecret
    .projectId("YOUR_PROJECT_ID")
    .projectEnvironment("YOUR_PROJECT_ENVIRONMENT")
    .build();

The private key: pass the contents of private.pem, or the private key as a JWK. The SDK picks ES256 or RS256 from the key type. The Java SDK needs an unencrypted PKCS#8 PEM (-----BEGIN PRIVATE KEY-----), which the openssl commands above produce, or a JWK.
Python: install the private-key extra, which adds the libraries used for signing.
Environment variables: each SDK also reads the key from PIPEDREAM_PRIVATE_KEY, alongside PIPEDREAM_CLIENT_ID.
Optional key ID: set keyId (key_id in Python) or PIPEDREAM_KEY_ID to send the key ID from Manage keys as the assertion’s kid. It’s useful during key rotation and for debugging, but not required.
One credential at a time: a client uses either a client secret or a private key. Passing both is an error.

Sign a client assertion yourself

If you’re not using an SDK, sign the client assertion yourself. You need these values:


Token URL	`https://api.pipedream.com/v1/oauth/token`
Assertion audience (`aud`)	`https://api.pipedream.com`
Client ID (`iss` and `sub`)	Shown when you create the client, and in the Pipedream UI’s list of API clients

The client assertion is a JWT signed with your private key:

Header	Value
`alg`	`ES256` for an EC key, `RS256` for an RSA key. Must match the registered key.
`kid`	Optional. The key ID from Manage keys. Without it, Pipedream tries each of the client’s keys.
`typ`	Optional. `client-authentication+jwt` is recommended.

Claim	Value
`iss`	Your client ID
`sub`	Your client ID
`aud`	`https://api.pipedream.com`, as a string. This is Pipedream’s issuer identifier. The token endpoint URL is not accepted.
`exp`	Expiration time, at most 1 hour in the future. A short lifetime such as 60 seconds is recommended.
`jti`	A unique ID for this assertion, such as a random UUID. Each assertion can be used only once.
`iat`, `nbf`	Optional. Must not be in the future.

Pipedream allows 30 seconds of clock skew.

Sign a new assertion for every token request, including retries. An assertion is rejected if its jti has already been used.

Request an access token

Send the assertion to the token endpoint with client_assertion_type set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer. Don’t send a client_secret or an Authorization header with it.

curl https://api.pipedream.com/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=<client_id> \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=<signed_jwt> \
  -d 'scope=connect:accounts:read connect:accounts:write'

The endpoint accepts form-encoded or JSON bodies. The response, the scope parameter, and the resulting access token work exactly as they do for a client secret. These examples sign an assertion and request an access token without an SDK:

// npm install jose
import { randomUUID } from "node:crypto";
import { readFileSync } from "node:fs";
import { importPKCS8, SignJWT } from "jose";

const CLIENT_ID = process.env.PIPEDREAM_CLIENT_ID!;
const privateKey = await importPKCS8(readFileSync("private.pem", "utf8"), "ES256");

async function getAccessToken(): Promise<string> {
  const assertion = await new SignJWT({})
    .setProtectedHeader({ alg: "ES256", typ: "client-authentication+jwt" })
    .setIssuer(CLIENT_ID)
    .setSubject(CLIENT_ID)
    .setAudience("https://api.pipedream.com")
    .setIssuedAt()
    .setExpirationTime("60s")
    .setJti(randomUUID())
    .sign(privateKey);

  const res = await fetch("https://api.pipedream.com/v1/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: CLIENT_ID,
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: assertion,
    }),
  });
  if (!res.ok) throw new Error(`Token request failed: ${res.status} ${await res.text()}`);
  const { access_token } = await res.json();
  return access_token;
}

# pip install "pyjwt[crypto]" requests
import os
import time
import uuid

import jwt
import requests

CLIENT_ID = os.environ["PIPEDREAM_CLIENT_ID"]
with open("private.pem") as f:
    PRIVATE_KEY = f.read()

def get_access_token() -> str:
    now = int(time.time())
    assertion = jwt.encode(
        {
            "iss": CLIENT_ID,
            "sub": CLIENT_ID,
            "aud": "https://api.pipedream.com",
            "iat": now,
            "exp": now + 60,
            "jti": str(uuid.uuid4()),
        },
        PRIVATE_KEY,
        algorithm="ES256",
        headers={"typ": "client-authentication+jwt"},
    )
    res = requests.post(
        "https://api.pipedream.com/v1/oauth/token",
        data={
            "grant_type": "client_credentials",
            "client_id": CLIENT_ID,
            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            "client_assertion": assertion,
        },
    )
    res.raise_for_status()
    return res.json()["access_token"]

Access tokens expire after 1 hour, so cache the token and request a new one before it expires. Configuring OAuth libraries Libraries that support private_key_jwt work with Pipedream, but some default the aud claim to the token endpoint URL, which Pipedream rejects. Set the audience to https://api.pipedream.com:

Authlib (Python): PrivateKeyJWT uses its first argument as aud, so register PrivateKeyJWT("https://api.pipedream.com") and still call fetch_token("https://api.pipedream.com/v1/oauth/token"). For an EC key, pass alg="ES256" and give the session a joserfc.jwk.ECKey as its client_secret. A PEM string works only for RSA keys. Authlib’s default assertion lifetime of 1 hour is accepted.
Spring Security: use a jwtClientAssertionCustomizer to set the aud claim.

Rotate keys

A client can have up to two public keys at once, so you can rotate without downtime:

Generate a new key pair.
In the client’s … menu, click Manage keys, paste the new public key, and click Add key.
Deploy your app with the new private key. Set kid in the assertion header to the new key’s ID.
Once Last used for the old key stops updating, remove the old key.

A client always keeps at least one key. Last used is updated at most every 10 minutes.

Errors

Status	`error`	Meaning
`400`	`invalid_request`	The request is malformed: a wrong `client_assertion_type`, a parameter sent more than once, client credentials in the query string, or a `client_secret` or `Authorization` header sent along with an assertion.
`401`	`invalid_client`	The assertion was rejected. Check the signing key and `alg`, `kid`, `iss` and `sub` (both your client ID), `aud` (exactly `https://api.pipedream.com`), and `exp`, and make sure the `jti` wasn’t used before. This is also returned when a public-key client sends a client secret.
`503`	`temporarily_unavailable`	Pipedream couldn’t check the assertion. Retry after the `Retry-After` interval, with a newly signed assertion.

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:

Scope	Description
`*`	Full access to every OAuth-protected endpoint
`connect:*`	Full access to all Connect API endpoints (apps, components, projects, triggers, accounts, etc.)
`connect:accounts:read`	List and fetch Connect accounts for an external user
`connect:accounts:write`	Create or remove Connect accounts
`connect:actions:*`	Full access to Connect actions
`connect:apps:*`	List and fetch apps and app categories in the Pipedream registry
`connect:deployed_triggers:read`	Read deployed triggers and related data like events, pipelines and webhooks
`connect:deployed_triggers:write`	Modify or delete deployed triggers
`connect:projects:read`	List and fetch projects, and read project environment webhooks
`connect:projects:write`	Create, update, and delete projects, and manage project environment webhooks
`connect:proxy`	Invoke the Connect proxy
`connect:tokens:create`	Create Connect tokens
`connect:triggers:*`	Full access to Connect triggers
`connect:usage:read`	List Connect usage records for a time window
`connect:users:read`	List and fetch external users
`connect:users:write`	Delete external users
`connect:workflow:invoke`	Invoke Connect workflows on behalf of a user

The table above is the complete list of scopes, and each scope must be requested exactly as written. There are no other :read / :write variants — for example, connect:apps:read is not a valid scope, so use connect:apps:* to grant access to the List apps and List app categories endpoints.Requesting an unrecognized scope fails with an invalid_scope error when you request the access token, not when you call the endpoint.

Revoking a client secret

Public-key clients have no secret. To replace a public key, see Rotate keys.

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.

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"
});

from pipedream import Pipedream

pd = Pipedream(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    project_id="YOUR_PROJECT_ID",
    project_environment="YOUR_PROJECT_ENVIRONMENT"
)

result = pd.create_connect_token(
    external_user_id="user-123",
    # Optional: customize TTL (defaults to 4 hours)
    expires_in=3600,  # 1 hour
    # Optional: restrict scopes (defaults to "connect:*")
    scope="connect:accounts:read connect:accounts:write"
)
token = result.token
expires_at = result.expires_at

curl -X POST https://api.pipedream.com/v1/connect/{project_id}/tokens \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "external_user_id": "user-123",
    "expires_in": 3600,
    "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 a subset of the OAuth scopes. Because Connect tokens are used client-side, they can only be granted scopes for the endpoints your end users call directly from the browser. 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 to Connect tokens). Available scopes:

Scope	Description
`connect:*`	Full access to all Connect API endpoints available to Connect tokens
`connect:accounts:read`	List and fetch Connect accounts for an external user
`connect:accounts:write`	Create or remove Connect accounts
`connect:actions:*`	Full access to Connect actions
`connect:apps:*`	List and fetch apps and app categories in the Pipedream registry
`connect:deployed_triggers:read`	Read deployed triggers and related data like events, pipelines and webhooks
`connect:deployed_triggers:write`	Modify or delete deployed triggers
`connect:proxy`	Invoke the Connect proxy
`connect:triggers:*`	Full access to Connect triggers

Connect tokens cannot be granted the * scope. The maximum scope available is connect:*.The following scopes are available to OAuth access tokens only, and requesting any of them when creating a Connect token returns a 400 error: connect:projects:read, connect:projects:write, connect:tokens:create, connect:usage:read, connect:users:read, connect:users:write, and connect:workflow:invoke.

Tokens

Apps

Accounts

External Users

Actions

Triggers

Deployed Triggers

Components

OAuth Clients

App Overrides

Projects

Project Webhooks

Connect Usage

File Stash

OAuth Access Tokens

Creating an OAuth client

How to get an access token

Private key JWT

Create a public-key client

Authenticate with the SDKs

Sign a client assertion yourself

Request an access token

Rotate keys

Errors

OAuth scopes

Revoking a client secret

OAuth security

Connect Tokens

Creating a Connect token

Connect token TTL

Connect token scopes

​OAuth Access Tokens

​Creating an OAuth client

​How to get an access token

​Private key JWT

​Create a public-key client

​Authenticate with the SDKs

​Sign a client assertion yourself

​Request an access token

​Rotate keys

​Errors

​OAuth scopes

​Revoking a client secret

​OAuth security

​Connect Tokens

​Creating a Connect token

​Connect token TTL

​Connect token scopes

OAuth Access Tokens

Creating an OAuth client

How to get an access token

Private key JWT

Create a public-key client

Authenticate with the SDKs

Sign a client assertion yourself

Request an access token

Rotate keys

Errors

OAuth scopes

Revoking a client secret

OAuth security

Connect Tokens

Creating a Connect token

Connect token TTL

Connect token scopes