What Is an API Key? – Definition and How It Works
Learn what an API key is, how it differs from a token and a password, where it belongs in a request, and how to store and rotate one safely.
An API key is a secret string that identifies the caller of an API. It answers "which account is this" and, in most implementations, does little more than that.
1. What Is an API Key?
A key is an opaque credential issued by a service to an account.
- Key idea: identification and attribution, so usage can be counted, limited, and billed.
- Mechanism: the caller includes the key with each request; the service looks it up and applies that account's limits.
- Goal: control access without an interactive login on every call.
2. Key, Token, Password — the Differences
| Credential | Represents | Lifetime | Typical use |
|---|---|---|---|
| API key | An application or account | Long-lived until rotated | Server-to-server calls |
| Access token | A delegated, scoped grant | Short-lived, refreshable | User-authorised access |
| Password | A human identity | Long-lived, user-chosen | Interactive login |
The important distinction is scope and expiry. A leaked short-lived token expires; a leaked API key keeps working until someone revokes it.
3. Where the Key Goes
Almost always a request header. Two shapes dominate:
Authorization: Bearer <key>
X-Api-Key: <key>
Some services define their own header name, and that name is part of the contract — the correct key sent under the wrong header authenticates nothing, and the failure usually surfaces as a generic unauthorised error.
Query-string keys still exist and should be avoided where possible: URLs appear in server logs, proxy logs, browser history, and referrer headers.
4. Storing a Key Safely
- Environment variables or a secret manager, never source code.
- Excluded from version control, with a committed
.env.examplenaming the variable and holding no value. - Never in client-side code. Anything shipped to a browser or mobile app is public, however obfuscated.
- Never logged. Redact before printing requests, and be careful with debug modes that dump full headers.
5. Rotation and Revocation
Keys should be rotatable without downtime, which means the service must allow more than one active key per account: issue the new key, deploy it, confirm traffic has moved, then revoke the old one.
If a key is exposed — committed, pasted, or logged — rotation is the only real remedy. Deleting the commit does not help, because the history and any copies remain.
6. What a Key Does Not Do
- It does not authorise a user. It identifies an account, not a person acting within it.
- It does not protect the payload. Transport security comes from TLS.
- It does not scope by default. Unless the service offers per-key permissions, one key usually carries the full account's rights.
7. Common Misconceptions
- "A key in a mobile app is safe." Application binaries can be inspected; embedded keys are public.
- "Obfuscation is protection." Encoding is not encryption, and both are reversible by whoever holds the artefact.
- "Rotating breaks everything." Only if the service allows a single active key; overlapping keys make rotation routine.
- "A key proves the request is legitimate." It proves whoever sent it holds the key.
8. Summary
An API key identifies the calling account so a service can authenticate, meter, and bill it. It belongs in a request header whose exact name is part of the API's contract, and it must live in environment configuration or a secret manager.
Treat exposure as compromise and rotate immediately. The practical difference between a key and a token is expiry, and that difference is why long-lived keys deserve stricter handling.