API Keys

Plaidly uses API keys for server-to-server authentication. Keys are passed via the X-API-Key header.

Key types

Keep secret keys on your server only — never expose them in frontend code, mobile apps, or public repos.

Getting a key

There is no dashboard signup flow to create a key ahead of time. A key is issued as part of merchant registration (POST /v1/merchants) and returned exactly once in the response body — copy api_key immediately, there is no "reveal" screen afterward.

Each merchant has one active api_key at a time (plus, briefly, one overlapping previous key during a rotation window) — this is not a multi-named-key system where you create and delete individual keys independently.

Rotating a key

Use Rotate credentials (POST /v1/me/credentials/rotate) rather than creating a second key:

1. Call rotate — you get a new api_key back, and the old one keeps working until previous_api_key_expires_at
2. Update your app to use the new key
3. Call revoke (POST /v1/me/credentials/revoke) once you've confirmed the new key is live everywhere, to end the overlap early

Usage in requests

curl https://api.plaidly.io/v1/payment_sessions \
  -H "X-API-Key: plaidly_sk_live_..."

Permissions

Keys are scoped to your merchant account. All keys have the same permissions today. Finer-grained scopes (read-only, webhook-only) are not implemented.

Security

• Store keys in environment variables or a secrets manager (Vault, AWS Secrets Manager, etc.)
• Never commit keys to git
• If a key is compromised, rotate it immediately, then revoke the previous one instead of waiting out the overlap window