How to rotate API credentials
Replace a key without downtime.
When to rotate
- On a schedule
- When someone with access leaves
- Immediately if a key may have been exposed — in a log, a commit, a screenshot, a support ticket
The sequence
1. Provision a new key
2. Deploy it alongside the old one
3. Confirm traffic is using the new key
4. Revoke the old key
5. Confirm nothing broke
Never revoke before deploying. Overlap is what makes rotation a non-event rather than an outage.
Provisioning
New keys are provisioned by whoever administers your DiligenceID tenant. The key is shown once and stored hashed — it cannot be retrieved later, and support cannot recover it. If you lose it, provision another.
Give the new key the same scopes as the old one, and no more. Rotation is a good moment to notice a key has scopes it never uses.
Deploying
Read the key from your secret store at startup. If your application can pick up a changed secret without a restart, rotation is a configuration change; if not, it is a deploy.
Do not hard-code it, commit it, bake it into an image, put it in a query string, or log it.
Confirming
Before revoking, confirm the new key is actually carrying traffic. A key that was deployed but is not being used will not tell you anything until you revoke the old one and discover a service still holding it.
If a key is exposed
Revoke first, then investigate. A key in a public repository should be assumed compromised the moment it is pushed, including in history — rewriting history does not un-disclose it.
Then work out what it could reach: which environment, which scopes, and what was done with it.