Looking for the previous documentation?Go to v1.docs.pluggy.ai

Credentials and API keys

What the client ID, the client secret and the API key are, where each one may live, how to store and rotate the client secret, and what to do when a credential leaks.

View as Markdown

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#

CredentialWhat it isWhere it may live
Client IDIdentifies 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 secretProves you own the application. Shown once, when it is generated.Your server only: a secrets manager or an environment variable.
API keyCreated 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 /auth and reuse it until it expires, instead of calling POST /auth on every request. The lifetime and the rate limit of POST /authAPI are on their own pages. When a request answers 401 because 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 /auth with 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.

Was this page helpful?