Rotate Credentials

Use this if a key leaked, you're doing routine credential hygiene, or an agent's key needs to be re-scoped. Rotation keeps the previous credential valid for a short overlap window so in-flight callers (and webhook receivers verifying with the old secret) don't break immediately.

Rotate an API key

curl -X POST https://api.plaidly.io/v1/me/credentials/rotate \
  -H "X-API-Key: your_current_api_key" \
  -H "Content-Type: application/json" \
  -d '{"credential_type": "api_key"}'

Response is the full Merchant object with a new api_key and a previous_api_key_expires_at timestamp. Both the old and new key authenticate until that timestamp.

Rotate a webhook secret

curl -X POST https://api.plaidly.io/v1/me/credentials/rotate \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"credential_type": "webhook_secret"}'

During the overlap window (previous_webhook_secret_expires_at), Plaidly signs each webhook delivery with both the new and the previous secret (multiple v1= values in X-Plaidly-Signature, comma-separated) so your receiver can switch verification secrets without dropping events. See Webhooks for the signature format.

End the overlap early

Once you've confirmed every caller/receiver is using the new credential, revoke the old one immediately instead of waiting out the window:

curl -X POST https://api.plaidly.io/v1/me/credentials/revoke \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"credential_type": "api_key"}'

credential_type is api_key or webhook_secret. Revoke ends the most recent rotation's overlap window — it does not affect a credential that was never rotated.

Operational note

Rotation and revocation both require an already-authenticated request (X-API-Key or bearer). If you have truly lost both the current key and any way to authenticate, there is no self-service recovery path — this is a hard boundary, not a gap: Plaidly never stores api_key/webhook_secret in a recoverable form, only the values themselves at issuance time (see Register a merchant).