Skip to content
PayloadPuffin.
Join the waitlist

Rotate an API key

To replace an API key secret without interrupting your service, rotate the key and choose a grace period. The old secret keeps working during that period, so you can deploy the new secret before the old one stops. The key keeps its ID, name, scopes and expiry.

You need the owner or admin role in your organization. Rotation happens in the console. The public API has no operation for it.

Rotate the key

  1. Open API Keys and select the key.
  2. In the API key section, click Rotate API key.
  3. In Expire old key, choose how long the old secret keeps working: immediately, or in 1 hour up to in 7 days.
  4. Click Rotate key.
  5. Copy the new secret from the dialog. It's shown only once.

The panel now lists a Current and a Previous secret, and says until when the previous one still works. The grace period never outlasts the key's own expiry.

Deploy the new secret

  1. Replace the old secret everywhere it's used, such as PAYLOADPUFFIN_API_KEY in each service.
  2. Send a request with the new secret to confirm it works.

Last used in the console can't tell you which secret a request used. It records use of the key, and it updates at most once an hour. Track the rollout in your own deployments instead.

Revoke the old secret

The old secret stops working on its own when the grace period ends. To stop it sooner, click Revoke previous API key next to the Previous secret and confirm with Revoke previous key. The current secret keeps working.

Revoking can take up to a minute to take effect.

Limits

  • A key has at most two secrets. While the previous secret still works, the console disables Rotate API key. Revoke the previous secret or wait for it to expire first.
  • An expired or deleted key can't be rotated. Create a new key instead.
  • If a secret has leaked, rotate with immediately, or delete the key. Deleting stops both secrets.