Rotate and scope API keys
A single admin key with no expiry, pasted into an environment file, is the credential that ends up in a public repo. Provision narrowly, store centrally, rotate, and revoke.
Procedure
- Read the provider's scope model and grant only what each job needs (read-only where possible).
- Create a distinct key per service and environment; never share one across prod and dev.
- Store in a secret manager (
aws secretsmanager get-secret-value, Vault, SOPS), not in committed.envor code. - Set an expiry/rotation cadence and automate rotation with an overlap window where both keys work.
- Revoke the old key after the new one is confirmed, then prove the old key now fails:
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $OLD" "$API/v1/me" # expect 401 - Log which key id made which call so a leaked key can be traced.
- Alert before expiry so rotation is not a surprise outage.
Pitfalls
- Keys pasted into source, CI logs, or chat leak on the first push; assume compromise and rotate.
- An admin-scoped key on a read-only job violates least privilege.
- Rotating with no overlap window breaks consumers at the switch instant.
- Some providers display a key only once at creation; losing it forces a recreate, so store immediately.
- Unused keys linger; audit and revoke anything with no calls in 90 days.
Verification
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $OLD" "$API/v1/me" # 401
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $NEW" "$API/v1/me" # 200
curl -s -H "Authorization: Bearer $NEW" "$API/v1/scopes" | jq . # narrow scope list
Report: "Rotated key id k-92; old revoked (401), new active (200), scopes items:read."