Accessing credentials via API

When you connect an account, you can use its credentials in workflows, authorizing requests to any app. Pipedream manages the OAuth process for OAuth apps, ensuring you always have a fresh access token for requests.

You can also access account credentials from the Pipedream API, using them in any other tool or app where you need auth.

The credentials API is in beta

Accessing credentials via API is in beta, and we're looking for feedback. Please let us know (opens new window) how you're using it, what's not working, and what else you'd like to see.

During the beta:

• All API calls to /v1/accounts/* are free.
• The API is subject to change.

• Using the credentials API
• Caching credentials
• Security

Using the credentials API

1. Connect your account
2. On https://pipedream.com/accounts (opens new window), find your account and click the ... to the right of the account,
3. Copy Account ID

4. Make a request to the Get account credentials endpoint.

export default defineComponent({
  props: {
    pipedream: {
      type: "app",
      app: "pipedream",
    },
    accountId: {
      type: "string",
      label: "Account ID",
    },
  },
  async run({ steps, $ }) {
    const url = `https://api.pipedream.com/v1/accounts/${this.accoundId}?include_credentials=1`;
    const headers = {
      "Content-Type": "application/json",
      Authorization: `Bearer ${this.pipedream.$auth.api_key}`,
    };

    const response = await fetch(url, {
      method: "GET",
      headers,
    });
    if (!response.ok) throw new Error(`API request failed: ${response.status}`);
    return await response.json();
  },
});

import requests

def handler(pd: "pipedream"):
    headers = {
      'Content-Type': 'application/json',
      'Authorization': f'Bearer {pd.inputs["pipedream"]["$auth"]["api_key"]}',
    };
    r = requests.get("https://api.pipedream.com/v1/accounts/<ACCOUNT_ID>?include_credentials=1", headers=headers)
    return r.json()

curl 'https://api.pipedream.com/v1/accounts/<ACCOUNT_ID>?include_credentials=1' \
  -H "Authorization: Bearer <PIPEDREAM_API_KEY>"

const url = `https://api.pipedream.com/v1/accounts/<ACCOUNT_ID>?include_credentials=1`;
const headers = {
  "Content-Type": "application/json",
  Authorization: `Bearer <PIPEDREAM_API_KEY>`,
};

const response = await fetch(url, {
  method: "GET",
  headers,
});
if (!response.ok) throw new Error(`API request failed: ${response.status}`);

// Credentials are in data.credentials
const { data } = await response.json();

import requests

headers = {
  'Content-Type': 'application/json',
  'Authorization': f'Bearer <PIPEDREAM_API_KEY>',
};
r = requests.get("https://api.pipedream.com/v1/accounts/<ACCOUNT_ID>?include_credentials=1", headers=headers)

# Credentials are in data.data.credentials
data = r.json()

5. It's not necessary to fetch credentials on every request to your app. You should cache credentials in your own DB, refreshing them only when necessary.

Caching credentials

Access tokens for most OAuth services are valid for at least one hour. Some tokens have a longer expiry, and some are static until rotated or revoked.

The response from /v1/accounts/:id?include_credentials=1 contains an expires_at field, an ISO timestamp representing the expiry of the current token. This maps to the expires_at timestamp in the OAuth access token response. While tokens are not guaranteed to be valid until expiry, they are for most APIs in practice. We recommend caching credentials with the expires_at timestamp, using the tokens until expiry, retrieving new credentials only after expiry or when you encounter auth errors when making your API request.

If expires_at is missing or null, the credentials do not expire.

/*** PSEUDO-CODE — use this as a guide ***/

// Fetch the most-recent token and expiry from cache / DB
const cache = Cache();
const { oauth_access_token, expires_at } = await cache.get("credentials");

// Only fetch new tokens when expired
let token = oauth_access_token;
if (expires_at && new Date(expires_at) < new Date()) {
  const url = `https://api.pipedream.com/v1/accounts/<ACCOUNT_ID>?include_credentials=1`;
  const headers = {
    "Content-Type": "application/json",
    Authorization: `Bearer <PIPEDREAM_API_KEY>`,
  };

  const response = await fetch(url, {
    method: "GET",
    headers,
  });
  if (!response.ok)
    throw new Error(`Unable to fetch token: ${response.status}`);

  const { data } = await response.json();
  const newToken = data?.credentials?.oauth_access_token;
  if (!newToken) throw new Error("No access token");
  token = newToken;
}

// Use `token` in API requests. Handle credentials errors and
// fetch new credentials from Pipedream as necessary

Since these credentials are sensitive, you should encrypt them in the DB or data store you're using, decrypting them only at runtime when authorizing API requests.

Security

See our security docs for details on how Pipedream secures your credentials.

Connected accounts are private by default. You can manage access control to expose them to other members of your workspace.