credentials

Store an upstream API credential — add a secret to the vault for broker injection

Store an encrypted credential in the vault for automatic broker injection.

Values are encrypted at rest and never returned after creation. Set api_id to bind the credential to an API; the broker will inject it automatically when proxying calls to that API.

auth_type reference

Set auth_type to tell the broker how to inject the credential into upstream requests. Based on the Postman auth type taxonomy.

auth_type	Status	Broker injects	value	identity
bearer	✅ implemented	Authorization: Bearer {value}	Token, PAT, or OAuth access token	Not used
basic	✅ implemented	Authorization: Basic base64({identity or "token"}:{value})	Password or PAT	Username (optional — defaults to "token" if omitted, works for GitHub PATs)
apiKey	✅ implemented	Custom header or query param = {value}	API key	For compound schemes (e.g. Discourse Api-Key + Api-Username): set identity to the username — one credential covers both headers when the overlay uses canonical Secret/Identity scheme names
oauth2	⚠️ partial	Authorization: Bearer {value} — token must be pre-obtained	Access token (Pipedream-managed flows only via pipedream_oauth)	Not used
digest	🔲 planned	RFC 2617 challenge-response (nonce/HMAC handshake)	Password	Username
jwt	🔲 planned	Authorization: Bearer {signed_jwt} — auto-generated from signing key	Private key or secret	Key ID (kid) — signing algorithm and claims go in context
aws_sig4	🔲 planned	Authorization: AWS4-HMAC-SHA256 ... signed headers	AWS Secret Access Key	AWS Access Key ID — region and service go in context
oauth1	🔲 planned	HMAC-SHA1 signed request (nonce + timestamp)	OAuth secret	OAuth consumer key
hawk	🔲 planned	Authorization: Hawk ... HMAC request signing	Hawk secret	Hawk key ID
ntlm	🔲 not planned	Windows NTLM challenge-response	Password	Username + domain
akamai_edgegrid	🔲 not planned	Akamai EdgeGrid signing	Client secret	Client token + access token in context

Notes:

pipedream_oauth is a reserved value written by the Pipedream integration — do not set it manually.
For oauth2 full flows (auth code, client credentials, PKCE, token refresh) see the roadmap.
context (not yet exposed) will hold auxiliary fields for multi-value schemes (JWT claims, AWS region/service, etc.).

Workflow

Call GET /apis/{api_id} — check security_schemes and credentials_configured to find gaps.
Post this endpoint with api_id, auth_type, value (and identity if needed).
The broker injects the credential automatically on every proxied call to that API.
To scope a credential to a specific toolkit: POST /toolkits/{id}/credentials.

If the API has no registered security scheme yet, submit an overlay first: POST /apis/{api_id}/overlays.

post/credentials

Request body

labelstring required

User-assigned credential label for identification

valuestring required

Raw credential value (API key, token, password) - encrypted before storage

identitystring nullable

Optional username, client ID, or other identity value (required for basic auth, optional for compound apiKey schemes)

api_idstring nullable

API ID to bind this credential to

auth_type'bearer' | 'basic' | 'apiKey' nullable

How this credential maps to the upstream API's authentication scheme. The broker uses this to find the right security scheme in the spec — it resolves by type, not by the bespoke scheme name in the overlay.

Value	Injects as	When to use
bearer	Authorization: Bearer {value}	REST APIs, OAuth access tokens, JWTs. GitHub REST API, Deepgram, Slack, etc.
basic	Authorization: Basic base64({identity??'token'}:{value})	HTTP Basic auth, git-over-HTTPS. Set identity to the username; omit for GitHub PATs (any username accepted).
apiKey	Custom header or query param = {value}	API key in a named header (X-API-Key, Api-Key, X-Auth-Key, etc.). For compound schemes (e.g. Discourse Api-Key + Api-Username) where the overlay uses canonical Secret/Identity scheme names, set identity to the username/account — a single credential covers both headers.

Example request

{
  "label": "GitHub PAT for jentic-mini",
  "value": "ghp_1234567890abcdefghijklmnopqrstu",
  "identity": "alice",
  "api_id": "api.github.com",
  "auth_type": "bearer"
}

Response

Successful Response

idstring required

Credential ID

labelstring required

Human-readable label for this credential

identitystring nullable

Identity field (username, client ID, etc.) for basic auth or compound API key schemes

api_idstring nullable

API this credential is bound to

auth_typestring nullable

Auth type: bearer, basic, or apiKey

created_atnumber nullable

Unix timestamp when created

updated_atnumber nullable

Unix timestamp of last update

account_idstring nullable

OAuth broker account ID (if from OAuth broker)

app_slugstring nullable

OAuth app slug (if from OAuth broker)

synced_atnumber nullable

Unix timestamp of last OAuth sync

Example response

{
  "id": "cred_abc123xyz",
  "label": "GitHub PAT for jentic-mini",
  "identity": "alice",
  "api_id": "api.github.com",
  "auth_type": "bearer",
  "created_at": 1672531200,
  "updated_at": 1672531200,
  "account_id": "oauth_abc123",
  "app_slug": "pipedream",
  "synced_at": 1672531200
}