Every application in the Dashboard has its own credentials, and together they reach every Item of that application. This page covers where each one may live and what to do when one is exposed.
The three credentials#
| Credential | What it is | Where it may live |
|---|---|---|
| Client ID | Identifies the application. Shown in the Dashboard at any time. | Your server. It is not a secret on its own, but it is only useful together with the client secret. |
| Client secret | Proves you own the application. Shown once, when it is generated. | Your server only: a secrets manager or an environment variable. |
| API key | Created by your server with POST /authAPI from the client ID and secret. It has full access to every endpoint of the Pluggy API. | Your server only, in memory. |
The front end never gets any of them. It gets a Connect Token, which your backend creates for one user.
Store the client secret like a password#
- Keep it in a secrets manager or an environment variable of your server. Never commit it, never log it, and never put it in front-end code, a mobile app, a ticket or a chat message.
- Read it from one place. Then a rotation is one update and a redeploy, not a search through repositories.
- New client secrets start with
pluggy_sk_and carry a checksum, so secret scanners can recognize one that ends up in a repository. See Client secret format. - The secret cannot be viewed again after the dialog that shows it is closed: not in the Dashboard and not through the API. If you lose it, generate a new one.
Use the API key from your server only#
- Create an API key with
POST /authand reuse it until it expires, instead of callingPOST /authon every request. The lifetime and the rate limit ofPOST /authAPI are on their own pages. When a request answers401because the key expired, create a new one. - The Node.js SDK (
pluggy-sdk) creates the API key and reuses it for you. - Never send an API key to a browser or a mobile app, and never log it: anyone who holds it has the same access as your server until it expires.
Separate development, production and tenants#
- One application per environment. Each application has its own client ID and client secret, so a development secret that leaks does not reach production data. See Environments and production.
- One application per tenant, if you serve several companies: Items are reachable only with the credentials of the application they were created under, so a leaked or rotated secret affects one tenant. See One application, or one per client?.
- Going to production rotates the secret. When an application is moved to production, its secret is rotated and the Dashboard asks an Owner or Admin to generate a new one. Plan the deploy of the new secret for that moment.
Rotate the client secret#
Generate a new secret in the Dashboard, on the application's page. Only a team's Owners and Admins can do it (see Team access).
- The current secret stops working immediately: from that moment
POST /authwith it fails. Any service that needs a new API key fails until it has the new secret, so know which services use it before you click. - The new secret is shown once. Store it in your secrets manager before closing the dialog.
- Generating a new secret does not revoke the API keys created before it. They keep working until they expire.
Recipe, with a script that checks the new secret before you redeploy: Rotate your client secret.
If a credential leaks#
A client secret. Generate a new one right away, deploy it, and remove the old value from wherever it was exposed (repository history, logs, tickets). Then check what was done with the application while the secret was valid.
An API key, or a secret that was used to create API keys you do not control. A new client
secret does not stop those keys. To cut them off before they expire, an Owner can disable the
application in the Dashboard: while it is disabled, the API rejects its API keys and Connect
Tokens, and POST /auth answers 401 with CLIENT_DISABLED. Everything that uses the application
stops with it, your own services included.
Re-enabling restores unexpired API keys
Disabling does not revoke an API key: it blocks the application. When you enable it again, every API key that has not expired yet works again, including a leaked one. Generate a new client secret while the application is disabled, and enable it only after the API keys created before the rotation have expired.
Does not protect against#
- A secret stolen from a server you control: rotation limits how long it stays useful, but your secrets manager and server access are yours to protect.
- An API key in front-end code: rotating the secret does not revoke it. Keep keys on the server.
Next: Connect Tokens.
