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. Generate the new secret, keeping the previous one#
Open your application in the Dashboard and click Generate new secret. Only the team's Owners and Admins can do it. Leave Keep the previous secret working for 24 hours ticked (the default): the new secret works at once, and the previous one keeps working with POST /auth for 24 hours, so your services carry on while you deploy. New secrets start with pluggy_sk_ (see Client secret format).
3. 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, and the secret you started from then stops working (an application never has more than two valid secrets).
4. Check it, then deploy#
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. Do it within the 24 hours: after that, the previous secret stops working.
5. Revoke the previous secret, or let it expire#
While the previous secret is valid, the application's page shows when it stops working. Once every service uses the new secret, click Revoke now to end it immediately, or let it expire at 24 hours. API keys already created with it keep working until they expire.
If the secret leaked#
Untick Keep the previous secret working for 24 hours when you generate the new one, so the leaked secret stops working immediately (if you already generated one keeping it, click Revoke now). Any service that needs a new API key fails until it has the new secret, so store it, check it with the script below and deploy it right away.
Then remove the leaked secret from wherever it was exposed (repository history, logs, tickets) and check what was done with it while it was valid. A new secret does not revoke the API keys created before it: they stop working when they expire. To cut those off sooner, see If a credential leaks.
Code#
// 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.')