What it is
An API key is a secret value the client sends, often in a header (Authorization: Bearer ... or x-api-key), so the server can recognise the caller. There is usually no user and no consent screen. Possession of the key is the whole authentication. Providers use keys for server-to-server calls, including model APIs, payment APIs and email APIs. Some keys are split into a public identifier and a secret; the public half is still not something to be careless with if it can spend money.
A key is not a JWT with claims, though some products issue JWTs and call them keys. A key is not OAuth. OAuth is how a user delegates access. API Authentication: Keys, Sessions and OAuth discusses choosing among these for an API you design. This page is how to handle keys you hold.
Why and when it is used
Use an API key when the API represents your application, not an end user: your server calls a model, a maps service, or a mail API. The key lives on the server. Use OAuth or your own session when the caller is a person and their rights differ. Use neither in the browser. A "public" key that can only call a restricted endpoint (some payment or map widgets) is a deliberate exception and still needs domain restrictions.
Do not create one global key for every developer, every environment and every customer. A leak then becomes a total leak, and you cannot tell who called.
How it works
The server stores a hash of the key or stores it in a vault and compares. The client reads the key from configuration at startup and sends it over HTTPS. Logs must not record it. A good provider lets you create several keys, name them (prod-web, dev-alice), set a spend or IP limit, and revoke one without revoking the others. Rotation means creating a new key, deploying it, confirming traffic moved, then deleting the old one. Overlap is fine. Downtime because you deleted first is not.
If you design an API that uses keys, show the secret once, store only a hash, and attribute every call to the key id in metrics. Rate-limit per key. A key in a query string will leak via access logs and Referer headers. Put it in a header.
Technologies and dependencies
Environment Variables or a secret manager, HTTPS, and a deploy path that can change the value without a code change (CI and CD if you have it). Frontend and Backend is the boundary. GitHub secret scanning and similar tools catch keys committed by accident; they do not replace not committing them. Authentication versus Authorization still applies after the key is accepted: a key may identify the app, and the app may still be forbidden from an action.
How to get started
- Create a key in the provider's console with the smallest permission and a spend cap if one exists.
- Put it in a local environment variable. Add the name, not the value, to
.env.example. - Read it in server code. Call the API. Confirm the value does not appear in your log line.
- Search the repo for the key string. If it is there, rotate immediately, do not only delete the file.
- Create a second key for production. Do not share the dev key with production.
- Write down who can create keys and how you will notice a bill spike.
If a framework exposes environment variables to the client when their name starts with a public prefix, do not put the key in a variable with that prefix.
Cautions and trade-offs
Keys in mobile apps and SPFx bundles can be extracted. Anything that ships to the user is public. Proxy those calls through your server. Keys in screenshots, tickets and chat logs are compromised; rotate.
A single key for a multi-tenant product means one customer can exhaust the quota for all. Issue per-tenant credentials or enforce your own limits in front. And a key does not expire unless the provider or you rotate it. Treat rotation as a feature you practise, not a disaster procedure you have never run. When a laptop is lost or a CI log might have printed the environment, rotate first and investigate second.