An API key is a long, randomly generated secret string that a client application sends with each request so that an API can identify the calling project, apply its permissions and quotas, and decide whether to serve the request. In the world of APIs, it is the simplest form of application-level authentication: it says which application is calling, not which human user is behind it.
API keys are common in Programming for public data services, mapping, payments, messaging and machine learning platforms, and for internal service-to-service calls. They are easy to issue and use, but because a key is a bearer credential, anyone who obtains it can act as its owner until it is revoked or rotated.
How an API key authenticates requests
An API key works as a shared secret between the provider and the client. The provider generates the key, stores it (ideally only as a hash) together with the owning account and its scopes, and shows the full value to the developer once. The client then attaches the key to every request, and the server looks up the key, checks its status and limits, and either processes the request or rejects it, typically with HTTP 401 Unauthorized for a missing or invalid key and HTTP 403 Forbidden for a key without the required permission.
Well-designed keys have at least 128 bits of entropy, commonly encoded as 32 to 64 characters, and often carry a readable prefix such as sk_live_ or pk_test_. Prefixes let developers tell environments and key types apart and let secret scanners detect leaked keys in code repositories automatically.
The table shows where clients usually place the key and how each option behaves.
| Placement | Example | Assessment |
|---|---|---|
| Authorization header | Authorization: Bearer sk_live_... | Preferred; standard and rarely logged |
| Custom header | X-API-Key: ... | Common and acceptable |
| Query parameter | ?api_key=... | Discouraged; appears in logs and history |
| Request body | JSON field in a POST | Rare; not usable for GET requests |
Every option requires HTTPS, because over plain HTTP the key travels in clear text and can be captured by anyone on the network path.
Types of API keys
Providers usually distinguish keys by who can see them and what they may do. The most important split is between publishable keys, which are meant to be embedded in browsers or mobile apps and grant only limited actions, and secret keys, which must stay on servers.
| Key type | Where it lives | Typical permissions |
|---|---|---|
| Secret key | Server or secrets vault | Full account access |
| Publishable key | Browser or mobile app | Restricted, low-risk actions |
| Restricted key | Server or a specific service | Selected scopes only |
| Test key | Development environments | Sandbox data, no real effects |
| Admin key | Operations tooling | Manages other keys and settings |
Publishable keys are safe only because the provider restricts them by design, for example by allowing them only to create a payment token or to load map tiles from approved referrer domains. A secret key that ends up in client-side code should be treated as compromised immediately.
API keys compared with other authentication methods
API keys are one of several ways to authenticate API traffic, and they are the weakest at expressing user identity and delegation. OAuth 2.0 issues short-lived access tokens on behalf of a user, a JWT is a signed token that carries claims and an expiry, and mutual TLS authenticates the client with a certificate during the connection handshake.
| Method | Identifies | Lifetime | Best fit |
|---|---|---|---|
| API key | Application or project | Long-lived until revoked | Server-to-server, simple public APIs |
| OAuth 2.0 access token | User and client | Minutes to hours | Acting on behalf of users |
| JWT | Subject and claims | Short, set by exp | Stateless verification between services |
| Mutual TLS | Client certificate holder | Months to years | High-trust internal or partner traffic |
| HMAC request signing | Key holder, per request | Long-lived secret | Tamper-proof requests, replay protection |
Many platforms combine methods: an API key identifies the project for billing and API rate limiting, while OAuth tokens authorize access to a particular user’s data. An API gateway often performs the key check before traffic reaches the backend.
Managing API keys securely
Secure handling of API keys depends more on operational discipline than on the key format. The core rule is that a secret key should never appear in source code, client bundles or logs; it belongs in environment variables injected at runtime or in a secrets manager such as HashiCorp Vault or a cloud provider’s equivalent.
- Apply least privilege: issue restricted keys with only the scopes a service needs.
- Use one key per service and environment, so a leak can be revoked without stopping everything.
- Rotate keys regularly, commonly every 30 to 90 days for sensitive systems, with an overlap window in which old and new keys both work.
- Restrict usage by IP range, referrer domain or mobile app identifier where the provider supports it.
- Monitor usage for unusual volume, regions or endpoints, and alert on spikes.
- Enable secret scanning in repositories and continuous integration pipelines.
Common mistakes and their consequences
Most API key incidents come from accidental exposure rather than cryptographic weakness. Automated bots scan public code repositories continuously, so a key pushed to a public repository can be abused within minutes, often for expensive compute or messaging services.
| Mistake | Consequence | Fix |
|---|---|---|
| Key committed to Git history | Leak persists after file deletion | Revoke the key, then rewrite history |
| Secret key in a mobile app | Extracted by decompiling the app | Proxy calls through a backend |
| Key passed in URL | Stored in logs and proxies | Move it to a header |
| One key shared by all services | Cannot revoke selectively | Issue separate keys |
| No expiry or rotation | Old leaks stay exploitable | Schedule rotation |
| Plain-text storage by provider | Database breach exposes all keys | Store only salted hashes |
Revocation is the first response to a suspected leak; deleting the file or the commit does not help, because copies already exist.
The short version
An API key is like a membership card for a software service. When a program asks the service for data, it shows the card, and the service checks whose card it is, what that member is allowed to do and how much they have already used this month.
The catch is that anyone holding the card is treated as the owner. That is why developers keep keys hidden, give each program its own card and cancel a card the moment it might have been copied.
Where it makes a difference
A small logistics company integrates a mapping service to calculate delivery routes. A developer first placed the secret key directly in the JavaScript of the dispatch web page. Within weeks, the monthly bill rose sharply because someone had copied the key from the page source and used it for their own traffic.
The team revoked the exposed key, created a publishable key restricted to the company’s domain for displaying maps, and moved route calculations to a backend service that uses a restricted secret key stored in a secrets manager. They added a daily usage alert and a 90-day rotation schedule. Unexpected charges stopped, and the next leaked test key was caught by repository scanning before it reached production.