Skip to main content

Rotate and revoke keys

A key cannot be edited: its secret and its Scopes are fixed when you create it. To change either, create a new key and revoke the old one. Admins can do both under Settings → API keys.

What revoking does​

A revoked key can no longer be exchanged for a token: POST /v1/token answers 401 invalid_client.

Tokens already issued keep working until they expire, for up to 15 minutes. Revocation stops new tokens; it does not recall the ones in circulation. If you revoke a key because it leaked, assume whoever holds it can keep calling the API for another 15 minutes, and check what its Scopes allowed them to do.

Rotate without downtime​

  1. Create the new key, with the Scopes the service needs.
  2. Deploy the new ClientID and secret to the service.
  3. Once every instance runs with the new key, revoke the old one.

Nothing in between fails: both keys work until you revoke the old one, and an instance still holding a token from the old key can use it until it expires.

Lost the secret​

We keep only a hash of the secret, so it cannot be shown again. Rotate: create a new key, deploy it, revoke the old one.