API Key Management Guide: Lifecycle Best Practices

API keys are the simplest way to authenticate to an API, which is exactly why they are everywhere and why they leak so often. A key is a long string that grants access to whoever presents it. It is created in seconds, pasted into code, shared in chat, embedded in mobile apps and forgotten. Many keys never expire, carry more permission than needed and cannot be traced to an owner. This guide covers the full API key lifecycle, from deciding whether to use one at all to creating, scoping, storing, using, monitoring, rotating and retiring keys, for both keys you consume and keys you issue.

Key takeaways

An API key is a bearer credential: possession equals access. Treat every key as a password for a non-human identity.
Prefer something better where available: OAuth client credentials with short-lived tokens, workload identity federation or mTLS. Use API keys where a provider offers nothing else, or for low-risk identification.
Every key needs an owner, a narrow scope, restrictions on where it can be used, an expiry and a home in a secrets manager.
Assume keys will leak: scan continuously, alert on unusual use and be able to revoke and replace quickly.

When an API key is the right choice, and when it is not

Situation	API key suitable?	Better option
Third-party SaaS API that only offers keys	Yes, with controls	Ask the vendor for OAuth or federation support
Identifying a caller for rate limiting or analytics	Yes	Combine with token-based authentication for sensitive data
Service-to-service calls inside your cloud	No	Workload identity, IAM roles, managed identities
CI/CD access to cloud providers	No	OIDC workload identity federation
Browser or mobile app calling a sensitive API	No, keys in client code are public	User-based OAuth with a backend
Partner integrations with sensitive data	Rarely	OAuth with `private_key_jwt` or mTLS

The NHI Authentication Guide compares these methods in detail.

How API keys leak

Source code and repositories, including history, forks and public mirrors. Researchers found over 17,000 secrets in public GitLab repositories.
Client-side code: browser JavaScript and mobile apps. The Google API keys and Gemini exposure showed that keys considered harmless in client code can become dangerous when the services they reach change.
Container images, logs, tickets and chat.
Vulnerable software that exposes keys, as with the Gravity SMTP plugin vulnerability.
Malicious packages and extensions that harvest keys from developer machines, such as the JetBrains Marketplace AI plugin campaign.
Compromise of the provider that issued the keys, as in the BeyondTrust API key compromise.

These map to OWASP NHI2 Secret Leakage and NHI7 Long-Lived Secrets. The Secret Sprawl Challenge covers the wider problem.

The API key lifecycle

1. Request and create

Create keys through an approved process that records purpose, owner, consuming system and required scope.
Use service or organisation accounts to create keys, not personal accounts that disappear when someone leaves.
Create one key per consuming application and environment. Never share a key across systems.

2. Scope and restrict

Grant the narrowest permissions the provider allows: read-only, specific resources, specific APIs.
Apply every restriction available: source IP ranges, referrer or app restrictions, allowed APIs, rate limits.
Set an expiry. If the provider does not support expiry, record a review date and enforce it yourself.

3. Store

Store keys in a secrets manager and inject them at runtime. Never commit them to code, images or configuration files.
Restrict who and what can read each key; log access.
See the Secrets Management Guide.

4. Use

Send keys in request headers over TLS, never in URLs, where they end up in logs and browser history.
Keep keys out of application logs and error messages.
Where the provider allows, exchange the key for short-lived tokens rather than sending it on every request.

5. Monitor

Scan repositories, CI/CD, containers, collaboration tools and ticketing systems continuously for your key formats.
Monitor provider-side usage: new source IPs, volume spikes, new endpoints, and spend.
Subscribe to provider leak notifications and secret scanning partner programmes where available.

6. Rotate

Rotate on a schedule and immediately after suspected exposure or staff changes.
Use overlapping keys (create new, deploy, verify, revoke old) to avoid outages.
Automate rotation where the provider has an API for it.

7. Revoke and retire

Revoke keys when the integration ends, the owner leaves without handover or the key has been unused for a defined period.
Confirm revocation took effect by checking provider logs.
Remove the key from the secrets manager and inventory.

If you issue API keys to customers or partners

Generate keys with high entropy and a recognisable prefix so secret scanners can detect them.
Store only a hash of the key server-side, and show the full key once at creation.
Let customers scope keys, set expiry, restrict source IPs and create multiple keys per integration.
Show last-used time and usage per key so customers can find unused keys.
Join secret scanning partner programmes so leaked keys are reported and can be revoked automatically.
Offer OAuth or federation for customers who need stronger options.
Validate keys at the gateway, and still enforce object-level authorisation in the service. See the OWASP API Security Top 10.

Responding to a leaked key

Revoke or disable the key immediately. Do not wait to rotate gracefully if the exposure is public.
Issue a replacement and update consumers.
Review provider logs for use of the key since it was exposed, and investigate any unfamiliar activity.
Remove the key from where it leaked, including repository history, but assume copies exist.
Fix the cause: add scanning, move to a secrets manager or replace the key with a stronger method.

Practitioner checklist

Inventory API keys you hold and issue, with owner, purpose, scope, age and last use.
Replace keys with OAuth, workload identity or federation where the provider supports it.
One key per consumer and environment, scoped and restricted as tightly as possible, with an expiry.
Store in a secrets manager; never in code, images, client apps or logs.
Scan continuously for leaked keys and monitor provider-side usage.
Rotate on schedule and on exposure, using overlapping keys.
Revoke unused and orphaned keys.
Maintain and rehearse a leaked-key response procedure.

API Key Management Guide: The Full Lifecycle from Creation to Retirement