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

valuestring

identitystring nullable

api_idstring nullable

server_variablesobject nullable

auth_type'bearer' | 'basic' | 'apiKey' | 'none' 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.
none	(nothing injected)	No-auth APIs where the credential exists only to carry server_variables for routing.

schemeobject nullable

Self-describing injection rule. When set, the broker injects the credential directly from this blob without looking up the API spec or overlay at runtime. Format: {"in": "header", "name": "Authorization", "prefix": "Bearer "} or {"in": "header", "name": "X-Api-Key"}. Supports encode=base64 for Basic auth: {"in": "header", "name": "Authorization", "prefix": "Basic ", "encode": "base64"}. For compound schemes: {"secret": {"in": "header", ...}, "identity": {"in": "header", ...}}.

routesstring[] nullable

Hostnames or host+path patterns this credential should be injected into. Each entry is stored as (host, path_prefix) in credential_routes. Example: ["github.com", "api.github.com"].

Example request

{
  "auth_type": "bearer"
}

Response

Successful Response

idstring required

labelstring required

identitystring nullable

api_idstring nullable

auth_typestring nullable

server_variablesobject nullable

schemeobject nullable

routesstring[] nullable

created_atnumber nullable

updated_atnumber nullable

account_idstring nullable

app_slugstring nullable

synced_atnumber nullable