The API key lifecycle: scope, rotation, and emergency revocation

An API key is often created at the start of an integration and ignored until it expires or leaks. In production, it needs an owner, a purpose, a lifetime, and a revocation procedure. A managed lifecycle limits incident impact and lets teams replace a credential without taking the service offline.

Give every key an inventory record

Record the owning system, consumer, environment, purpose, permissions, issue date, expected rotation, and responsible team. A label such as prod-key-2 is not enough; a year later, nobody can tell which workflow will stop when it is revoked.

Do not share one key across development, test, and production. Independent applications should also have independent credentials. A shared secret hides the source of activity and forces every consumer offline when only one has been compromised.

Define access before issuance

Allow only the operations and resources the integration requires. A messaging client that submits notifications does not automatically need billing administration or user-management access. A background worker normally benefits from a dedicated service identity, a narrow API scope, and an explicit rate limit.

Network restrictions such as an IP allowlist can supplement permissions, but they do not replace them. Addresses change, and a stolen credential can still be abused from an otherwise trusted network path.

This follows the continuous-verification model described in our Zero Trust architecture guide: a trusted network location must not automatically authorise an action.

Deliver the secret without manual copying

Keep keys out of Git, tickets, wikis, container images, and shared chat. The application should receive the value from a secrets manager or protected runtime configuration. Log the secret identifier and access event, never the value itself.

Where the CI platform supports it, separate permission to use a secret from permission to display it. Passing a credential directly into a release process reduces the number of people and systems that can accidentally expose it.

Rotate without downtime

A robust rotation temporarily accepts two valid keys:

1. Issue a new key with the same minimal scope.
2. Deliver it to the consumer.
3. Switch the application and observe successful calls under the new identifier.
4. Stop intentional use of the old key.
5. Revoke it after a short, defined observation window.
6. Confirm that no further calls use the retired identity.

If a provider permits only one credential, rotation requires a coordinated maintenance window or an intermediate authentication design. Discover that constraint during architecture work, not during an incident.

Make audit data actionable

Retain the timestamp, key identifier, API method, target resource, result, and technical request origin. Avoid recording the credential, full personal-data payloads, or unnecessary headers. Useful anomalies include a new region, an unusual method, a rate spike, or activity after the consumer was meant to be retired.

For the interface itself, see our guide to API contract versioning.

When the API belongs to an external supplier, include credential rotation and audit evidence in the wider external-dependency resilience plan.

Prepare emergency revocation

The runbook must answer who can revoke, how quickly, which business process will stop, and how a replacement is issued. Removing a leaked value from Git is not revocation: the value may remain in history, caches, and build artefacts.

The response combines revocation, usage discovery, replacement, log review, and remediation of the exposure path. If the key held excessive permissions, inspect operations outside the application’s normal behaviour as a separate step.

A good API key is not a permanent string. It is a constrained service identity that can be located, rotated, revoked, and tied to a specific stream of requests.