Store, rotate and revoke API keys securely

Record a clear purpose for every key

An API key does not have a universal permission model. Check with the provider or in your implementation which identity it represents, which operations it permits, whether it expires and how it is revoked. The string alone does not answer these questions.

Keep an inventory without secret values: key identifier, application, environment, owner, permitted resources, last planned rotation and revocation mechanism. A non-secret identifier or suitably limited fingerprint allows identification. The complete key does not need to appear in a table.

Separate at least development from production and integrations with different tasks. A test credential then need not read customer data, and an export service need not manage users. A key restriction only works if the recipient enforces it during use. The OWASP secret lifecycle guidance connects creation, limited permissions, rotation, revocation and expiry.

Provide secrets where they are needed

For an outbound integration, the calling process needs the usable key. Provide it at runtime through your environment's secret management system. Grant access only to the service identities that need it. Include backups, administrative exports and the recovery path in this assessment.

An environment variable can help keep values out of source code. However, it is not a vault in its own right: startup scripts, diagnostic output, process permissions, container configuration and error reports may expose it. The entire provisioning path matters. Avoid commands in guides and runbooks that print complete keys to the screen or a log.

If you issue keys yourself and check incoming requests, the task differs. Depending on the design, the server can store a suitable irreversible verification value instead of the complete secret. This pattern cannot be applied to a client that must send the key to another API. Construction, secure random generation, comparison and revocation checks should follow a suitable existing component; inventing your own password scheme is not a prerequisite.

The Google Cloud recommendations are a specific provider example of restricted keys, avoiding client-side exposure and safe rotation. Individual restrictions available there are not general properties of other APIs.

Consider the entire request path

Transmit the key only through a protected channel intended for this purpose. If the service provides a header for secret keys, use it instead of a URL query parameter. URLs often end up in access logs, history, telemetry or shared error reports. Headers are not automatically secret storage either: redact them at the gateway, proxy, application and observability system.

An IP restriction can provide additional protection for known server egress addresses. It does not replace checking the key and its permissions. A browser referrer rule does not make an embedded secret key confidential either. Assess each feature against its documented protection boundary.

A server-side intermediary only meaningfully protects a secret provider key if its own access is controlled. An anonymously accessible proxy forwarding arbitrary paid jobs with your full permissions shifts the problem. It needs its own authentication, business constraints and, where appropriate, resource budgets.

Carry out a planned key rotation in a controlled way

The following sequence assumes that the service supports two temporarily valid keys. If it does not, you need a documented switchover time with an appropriate interruption plan.

1. Check consumers and permissions. Identify web processes, background jobs, queue workers and infrequent tasks. Give the new key the intended permissions, without adding more as a precaution.
2. Provide the replacement securely. Create a new version in the designated secret system. Keep the old value out of tickets and deployment output.
3. Migrate a limited set of consumers. Check a low-risk normal access and its expected result. HTTP 200 alone is insufficient if the service returns a different resource.
4. Migrate the remaining consumers. Observe errors and use by non-secret key identifier. Account for long-lived processes and cached configuration.
5. Revoke the old key. Then demonstrate that it no longer grants access and that the new credential still fulfils the required task. Use a controlled, non-mutating test path of your own.

Rotation is complete only when the old credential is ineffective. Deleting the string from the current deployment is insufficient. If unexpected errors occur, pause further rollout and clarify permissions, target environment and loaded version. During a purely planned rotation, an old configuration that remains secure can briefly provide a rollback path; document its extended validity.

A suspected leak changes the order

If a secret key has become public or may have been stolen, treat it as compromised. Block it through the designated mechanism and provision new access from a clean environment. Depending on the impact, this may require a deliberate interruption. Do not wait until the next scheduled rotation.

Preserve the event data needed for investigation with restricted access: when exposure began, which key identifier is affected and what use was observed. Do not copy the secret value into additional reports. Investigate affected resources, unusual actions and possible derivative credentials. The scope follows the actual permissions, not the application's name.

Then remove the source of exposure and stop the behaviour causing it. Deleting a Git commit, cleaning a log file or closing a chat neither revokes access nor retrieves existing copies. The OWASP Secrets Management incident response guidance treats revocation and addressing the cause as connected tasks. Do not reactivate a compromised key even to roll back a change.

How to recognise sound key management

Practise replacement first with purely synthetic credentials or your own test credentials. Check permitted and forbidden operations, expiry and revocation, and a forgotten background process. The result should show which credential was used when, without disclosing its value.

Also check whether browser assets, source control, logs and diagnostic paths may contain secrets. A search with no matches does not prove that every secret is absent; different systems need different controls. State the scope actually checked.

The API Security Check does not read secret stores or perform key rotation or access tests. If the actual question concerns user grants and their revocation, examine the appropriate authentication architecture and OAuth/OIDC instead. Sources checked: 27 September 2026.

Next steps