Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
PluggyDocs
← Back to Recipes

Rotate your client secret

Replace an application's client secret, on a schedule or because it may have leaked, with the shortest possible interruption.

Steps#

1. Read the secret from one place#

Every service that calls the Pluggy API should read the client secret from your secrets manager or an environment variable, never from code. Then a rotation is one update and a redeploy, not a search through repositories.

2. Prepare before you generate#

Generating a new secret invalidates the current one immediately: from that moment, POST /auth with the old secret fails. API keys already created keep working until they expire, so running services that reuse their API key carry on for a while, but any service that needs a new API key fails until it has the new secret. Know which services use the secret and how you will redeploy them.

3. Generate the new secret in the Dashboard#

Open your application in the Dashboard and generate a new client secret. Only the team's Owners and Admins can do it. New secrets start with pluggy_sk_ (see Client secret format).

4. Store it before closing the dialog#

The new secret is shown only once. Save it to your secrets manager right away; if you lose it, you have to generate another one.

5. Check it, then redeploy#

Confirm that the new secret creates an API key (the script below does it), then redeploy or restart every service that uses it, so each one creates its next API key with the new secret.

6. If the secret leaked, clean up after rotating#

Remove it from wherever it was exposed (repository history, logs, tickets) and check what was done with it while it was valid. Generating a new secret does not revoke the API keys created before it: they stop working when they expire.

Code#

javascript
// Run after storing the new secret: it fails loudly if the secret is wrong.
// Usage: PLUGGY_CLIENT_ID=... PLUGGY_CLIENT_SECRET=... node check-secret.mjs
 
const { PLUGGY_CLIENT_ID, PLUGGY_CLIENT_SECRET } = process.env
 
if (!PLUGGY_CLIENT_SECRET?.startsWith('pluggy_sk_')) {
  console.warn('This secret does not have the pluggy_sk_ prefix: is it the new one?')
}
 
const response = await fetch('https://api.pluggy.ai/auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientId: PLUGGY_CLIENT_ID,
    clientSecret: PLUGGY_CLIENT_SECRET,
  }),
})
 
if (!response.ok) {
  // Never print the secret itself.
  console.error(`POST /auth failed with ${response.status}: the secret was not accepted.`)
  process.exit(1)
}
 
const { apiKey } = await response.json()
console.log(apiKey ? 'The new secret works. Redeploy your services.' : 'Unexpected response.')