API key security: a password for an application

An API key is a secret string that a client sends with each request so the API can tell which application is calling. It names a program, not a person, and whoever holds the string can act as that program. That makes keys easy to issue and easy to lose. This guide covers where to keep one, how to send it, how to rotate and revoke it, and how to limit what it can do. It belongs to API security and expands the short key paragraph on API authentication.

Section API security Updated Sources OWASP, RFC 9110

Quick facts

Identifies
The calling application or integration, not a person; OWASP API2:2023 says API keys are for client authentication only
Format
No standard. RFC 9110 defines the Authorization header and the 401 challenge, not a key format
Property
Like a bearer token, anyone who holds it can use it (RFC 6750, section 1.2)
Where it goes
A header, over HTTPS. Never the URL, because URLs are logged (OWASP REST Security Cheat Sheet)
Where it lives
A secret store, not source code (OWASP Secrets Management Cheat Sheet)
Lifecycle
One key per integration, narrow permissions, rotation, immediate revocation on exposure
Does a WAF manage API keys?
No. It does not issue, store, validate or revoke them, and a copied key looks like the owner's

Sources: the OWASP REST Security Cheat Sheet (API keys, secrets in URLs), the OWASP Secrets Management Cheat Sheet (storage, rotation, detection, incident response), OWASP API2:2023 and OWASP API4:2023, RFC 6750 for the bearer comparison, and RFC 9110 for the HTTP header fields.

What an API key identifies

A key answers one question: which application is this? It does not say which person is behind the application, and unlike a signed JWT token it carries no expiry or claims. OWASP API2:2023 is direct about the limit: it lists API keys among the things that are not authentication on their own, and says they should be used for API client authentication only. When the API needs to know who a person is, use a mechanism built for users; OAuth security covers that route.

The key also behaves like a bearer credential. RFC 6750 defines a bearer token as one where any party in possession of it can use it, with no proof of holding key material. A plain API key works the same way. Nothing in the request distinguishes the owner from a person who copied the string, so every rule below is about keeping the string away from other people.

Why issue keys at all? The REST cheat sheet gives two reasons. A public API with no access control can be farmed, which runs up bandwidth or compute bills, and a key lets you tie usage to a client. Keys also let operators sell access by plan. The same text warns that keys given to third-party clients are relatively easy to compromise, and that you should not rely on API keys alone to protect sensitive, critical or high-value resources.

A valid key settles who is calling, nothing more. Whether this application may touch this particular record is another check, and skipping it is BOLA.

Where to keep a key and how to send it

Keep it out of code

The Secrets Management cheat sheet opens with the problem: many organisations have secrets hardcoded in plaintext in source code and scattered through configuration files, and it recommends centralising storage, provisioning, auditing and rotation. For a key this means a secrets manager or the secret store of your deployment platform, read by the service when it starts. The key is never committed, not even to a private repository, because repositories get cloned, forked and made public.

Apply least privilege, as the cheat sheet asks: only the services that make the call can read the key, and people do not need it at all in routine work. Use separate keys for development, testing and live traffic, so a leak from a test machine does not hand over the live key. The cheat sheet also asks you to audit when a secret was used and by whom, which is where a per-key usage record pays off later.

Send it in a header, over HTTPS

The REST cheat sheet says services must offer HTTPS only, which protects credentials in transit, including API keys. It also says passwords, tokens and API keys should not appear in the URL, because a URL can be captured in web server logs. RFC 9110 gives the general reason in section 17.9: URIs are meant to be shared, not secured, and many servers, proxies and user agents log or display them.

The standard place for credentials is the Authorization header, which RFC 9110 defines in section 11.6.2. Many APIs use their own header name for the key instead. That is a convention rather than a standard, and either works. The rule that matters is the one in the query string: even for bearer tokens, RFC 6750 says that sending them in the URL should not be done unless a header or body is impossible.

Same call, two ways to send the key (placeholder values only)
Avoid:   GET /v1/orders?key=<key> HTTP/1.1
         Host: api.example.com

Prefer:  GET /v1/orders HTTP/1.1
         Host: api.example.com
         Authorization: <scheme> <key>

In the first form the key is part of the address, so it can land in access logs, proxy logs, browser history and in a Referer header if the user follows a link. In the second it travels with the request metadata, which you can keep out of your own logs by masking it.

Scope, rotation and revocation

Issue narrow keys

Give each integration its own key. The Secrets Management cheat sheet notes that when services share one secret, finding the source of a leak becomes hard; with one key per integration the log shows who used what, and revoking one key does not break the others. Limit each key to the operations it needs, such as read-only access or a short list of routes, in line with the endpoint-by-endpoint checks you already run.

Restrict where a key may be used when you know the answer. A partner server with a fixed network address can be limited to it. For keys that run in browsers, an origin check helps against careless reuse on other sites, but it binds only well-behaved browsers and is not protection from someone who already holds the key.

Rotate on a plan

The cheat sheet says manual rotation is error-prone and recommends automating it or at least supporting it properly. A workable pattern for API keys is to allow two active keys per integration: issue the new one, let the client switch, then retire the old one. Without that overlap, rotation means downtime, and teams postpone it. The cheat sheet lists gradual, rapid and scheduled rotation as strategies and sets no fixed interval, so pick one you will actually follow.

Revoke at once

When a key is exposed, the incident-response section of the cheat sheet lists three steps: revoke the key immediately, rotate to a new one, and delete the old value from wherever it appeared, including code and logs. It adds that rewriting git history to remove a secret may cause other problems. Treat a key that touched a public place as burned whatever you do to the history. The REST cheat sheet also says to revoke a key when its client violates the usage agreement. Revocation is easy only if the server holds a record of valid keys; a design where it cannot disable one key without a deploy needs fixing first.

Where keys leak

Most key incidents are copies, not cryptography. The string ended up somewhere readable, and someone read it.

Common places a key escapes, and the alternative
PlaceWhy it leaksInstead
Source code and its historyA commit stays in history after the line is deleted, and a public repository can be read by anyoneLoad the key from a secret store at start
URL query stringLogs, proxies, browser history and shared links record URLsSend it in a header
Browser or mobile appAnything shipped to the client can be read by whoever has the appCall your own backend, which holds the key
Logs, tickets and chatPasted requests carry the header with themMask credentials before logging or sharing
Deployment configurationPipelines hold secrets for many systemsRestrict who can read them; the cheat sheet has a section on CI/CD

Public repositories. The cheat sheet suggests catching secrets before they are committed, through the IDE, tests or a pre-commit hook, and treating secrets as part of the attack surface during threat modelling. It also suggests running more than one detection tool and comparing results, since each misses some patterns. Scanning after the fact still helps, but a scanner that finds a key tells you it is already out.

Client applications. A key inside a web page script or a mobile bundle is not secret, because the client has to read it to send it. If the API is public by design, issue a separate low-privilege key for client use, restrict it as far as you can and give it tight limits. If the call needs real privileges, move it behind your server so the client never sees the key.

Limits per key

A key is the most precise subject for counting requests, because it names one integration; rate limiting by IP, user or key compares it with the alternatives. The REST cheat sheet says to require a key on every request to the protected endpoint and to answer with 429 Too Many Requests when calls arrive too quickly.

A per-key limit also caps what a leaked key is worth. A thief who holds a key gets that key's allowance and no more, and the spike shows up under that key's name in your usage record. For paid third-party services, OWASP API4:2023 adds a second angle: set spending limits for every provider your API calls, and where limits cannot be set, configure billing alerts. A leaked key that calls a metered service can cost real money before anyone looks.

Quotas that tie a key to a customer and a plan live in the application or its gateway, since that is where the key-to-customer mapping exists. Resource limits as a whole are covered on unrestricted resource consumption.

Where a WAF helps and where it does not

A WAF has no list of your valid keys and no way to tell a genuine one from a copy. A request carrying a stolen key passes like any other request, because everything the filter can inspect looks normal. Issuing, storing, rotating and revoking keys belong to your application and its secret store, and nothing at the edge replaces them. The same holds for leaked keys in repositories and apps: the WAF never sees those places.

What the edge does give you is narrow. Bridge WAF matches named attack categories in request traffic and applies rate limits per domain. A per-domain limit bounds what the whole domain accepts; it is not a quota per key, so keep per-key limits in your own layer. It also supports the habits around the key: credential stuffing and guessing against sign-in and key-management endpoints are the kind of traffic a limit slows, and a client over the cap receives a 429 response.

Start in monitor mode. Matches are logged while every request is still served, so you can read the monitor-mode log before turning on block. The three modes are in the box below.

Questions

What is an API key?

An API key is a secret string a client sends with each request so the API can tell which application is calling. It identifies a program, not a person, and whoever holds the string can act as that program. Treat it like a password.

Is an API key the same as a token or a password?

Not quite. A password proves a person, a signed token carries claims and an expiry, and an API key is usually a static string that names an application. Like a bearer token under RFC 6750, it works for anyone who holds it. OWASP says API keys should be used for client authentication only, not for user authentication.

Where should an API key go in a request?

In a header, over HTTPS. Keep it out of the URL, because URLs are logged by servers, proxies and browsers. RFC 9110 defines the Authorization header for credentials, and many APIs use a custom header for the key instead.

What should I do if an API key leaks?

Revoke it first, then issue a new one and remove the old value from the places it was exposed, including code and logs. Deleting a commit does not make the key safe again. Afterwards, review how the key was used while it was exposed.

Can a WAF protect an API key?

No. A WAF does not issue, store, rotate or revoke keys, and it cannot tell the real owner from someone using a copied key. It can filter attack patterns and apply limits per domain, while key handling stays in your application and its secret store.