An API asks for a key, you paste the string into a request, and the first call works. The next one returns 403. A teammate gets 429 with the same code. Later, you discover the key was committed to GitHub six weeks ago. These look like unrelated problems, but they become easier to investigate once you know exactly what an API key identifies, what the provider checks, and where the key travels.
An API key is a string that an API provider gives your application. Your code includes it in an API request so the provider can recognize which project, app or account is making the call. Depending on the service, it may be an access credential, a billing or quota identifier, or part of a larger authorization process. A valid key does not necessarily identify the person behind the request, and it does not mean every endpoint is permitted. You can have the right key and still receive 403 Forbidden because the account or project lacks access.
An API key travels from application code to the server, where restrictions and permissions determine whether the request is accepted. Deployment, rotation, and authentication choices affect how safely that key can be used. The examples use invented keys and a local test endpoint; no third-party account is needed to follow them.
If an API call fails, use its response code as a clue—not a complete diagnosis. The troubleshooting section explains how to narrow down authorization problems, restricted keys and usage limits.
What happens when a request carries an API key
If your application requests shipping estimates from another service, the provider gives your project an API key. Your backend includes that key in a call to /v1/estimates. Before returning a price, the provider may check whether the key is valid and active, whether the API is enabled, whether the request comes from an allowed application or network, and whether you have reached a usage limit. The exact checks depend on the provider.
When the call succeeds, you receive the shipping estimate. If it fails, the HTTP status gives you a clue, but not the whole explanation. A 401 often means the request has missing or invalid authentication; 403 means the provider refused the operation; and 429 usually means you have sent too many requests. Providers can use these codes differently, so read the error message and the provider's documentation alongside the status.
When a valid key still gets rejected, separate four questions. Which URL is the app calling? Which key did it send? Which project or account owns that key? And what is that project allowed to do? A provider can recognize the key and still refuse an action. That is why creating another key is rarely the best first fix.
A key can identify a project without authenticating a person
An API key does not mean the same thing at every provider. A standard Google Cloud API key mainly tells Google which project to associate with the request for usage and billing; it does not identify the signed-in person. Other providers issue secret keys that act more like account passwords for an API. Google also has authorization keys with different rules. Check what your provider means by “API key” before treating it as proof of a user’s identity.
Ask what the key proves for this specific API. A billing-project key may need OAuth as well—OAuth is a way for a user or application to grant limited access. A secret account key may let anyone who steals it make requests within that account’s permissions. A browser key intended to be visible needs tight website and API restrictions, because visitors can inspect browser code and requests.
An API key is not the same as an end-user login session. If your backend uses one provider key to make requests for 500 customers, the provider may recognize your application without knowing which customer made each request. Your backend must still check which customer can access each shipment, order, or other resource. One shared key does not replace permission checks for individual users.
Where the key goes in a real HTTP request
Providers decide the required format. Here are two common patterns, shown with placeholders rather than usable credentials:
GET /v1/estimates?postcode=411045 HTTP/1.1
Host: api.example.test
X-API-Key: YOUR_PROJECT_KEY
GET /v1/estimates?postcode=411045 HTTP/1.1
Host: api.example.test
Authorization: Bearer YOUR_SECRET_KEY
Neither header is a universal API-key standard. The first is common in custom APIs; the second is used by some vendors for keys and by others for OAuth access tokens. Check the provider's examples instead of guessing. Google Cloud APIs often accept x-goog-api-key. Copying a working key into the wrong header can produce the same error as a wrong key value.
Some providers allow a query parameter such as ?key=.... That can work, but URLs are more likely to be copied into browser history, monitoring, proxy logs, referral data, and support tickets. For Google APIs, Google recommends using a header or client library instead of putting a key in the query string. A header does not make a secret magically safe: request headers can also be logged if your infrastructure is configured carelessly.
For a backend, keep the secret outside source code and inject it through deployment secrets or a secrets manager. During local development, an environment variable is a reasonable starting point as long as its value is not committed, printed, or pasted into shared screenshots. Use HTTPS to prevent the key from travelling in cleartext over the network.
Try a small local API without a real provider account
This Node.js example shows the difference between a recognized key and permission to perform an action. It is a teaching endpoint, not a production authentication server. It intentionally uses fixed local example keys, so run it only on your own machine and never deploy those example values.
// save as demo-api.cjs; Node.js 20+
const http = require('node:http');
const { timingSafeEqual } = require('node:crypto');
const keys = new Map([
['demo-read-only', 'read'],
['demo-writer', 'write'],
]);
function equalKey(a, b) {
const left = Buffer.from(a);
const right = Buffer.from(b);
return left.length === right.length && timingSafeEqual(left, right);
}
http.createServer((req, res) => {
const supplied = req.headers['x-api-key'];
const match = [...keys].find(([key]) =>
typeof supplied === 'string' && equalKey(key, supplied));
const reply = (code, message) => {
res.writeHead(code, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ message }));
};
if (!match) {
res.setHeader('WWW-Authenticate', 'ApiKey realm="local-demo"');
return reply(401, 'API key missing or unknown');
}
if (req.url === '/admin' && match[1] !== 'write') {
return reply(403, 'Key lacks write permission');
}
if (req.url !== '/admin' && req.url !== '/estimate') {
return reply(404, 'Unknown path');
}
reply(200, 'Request accepted for this demo');
}).listen(3000, '127.0.0.1');
Start it with node demo-api.cjs, then use a terminal to make these calls. The host 127.0.0.1 is your own computer.
curl -i http://127.0.0.1:3000/estimate
curl -i -H 'X-API-Key: demo-read-only' http://127.0.0.1:3000/estimate
curl -i -H 'X-API-Key: demo-read-only' http://127.0.0.1:3000/admin
curl -i -H 'X-API-Key: demo-writer' http://127.0.0.1:3000/admin
The expected statuses are 401, 200, 403, and 200. Notice that /admin rejects a recognized key because the role associated with it is insufficient. A real provider might use scopes, products enabled for a project, an IP allowlist, a separate account role, or a billing requirement instead of this tiny role map. The exercise isolates the difference between identity and permission without any billing risk.
This demonstration uses exact-key matching. A real API service should store credentials securely, use appropriately generated high-entropy secrets, avoid making timing leaks in comparisons, support revocation, maintain audit records, and apply rate limiting. Do not use the Map or hardcoded example strings as a deployment pattern.
Restrictions determine how much a leaked key can do
A restriction limits where, how, or for what a key can be used. Not every provider supports every restriction. On Google Cloud, common choices include which APIs the key may call and which sites, IP addresses, or app contexts may use it. Those checks can reduce misuse, but they do not make a secret safe to publish indiscriminately.
For example, if your server always connects to the provider from the same public IP address, an IP restriction can allow calls only from that address. This works only if the provider supports it and your server’s outgoing IP does not change. A website using a deliberately public Google Maps key may instead restrict which website addresses and APIs can use it. Neither restriction is a reason to expose a secret meant only for the server. In cloud hosting, double-check the outgoing IP before adding an IP restriction; a change could block your working application.
The user-visible failure can be confusing. The key string is correct, yet a new staging domain is blocked because the allowlist includes only production. A teammate tests with a VPN and gets a denial because the source IP changed. Or a perfectly formatted key fails because the required API was never enabled in the project. Before generating a new key, inspect restrictions and the exact provider error.
Give each application or environment its own key when the provider permits it. If staging and production share one credential, an experimental integration can consume production quota, and revoking a compromised staging key may cause an avoidable production outage. Separate keys also make usage logs easier to interpret.
Browser keys and server keys need different treatment
Anything included in JavaScript sent to a visitor’s browser is visible to that visitor. Hiding a key behind an environment-variable name, minified code, or obfuscation does not make it secret. For a server-only credential, let the browser call your backend. Your backend checks what the signed-in user is allowed to do, then calls the third-party API using the secret stored on the server.
Some products deliberately support browser-visible keys. For example, Google Maps web integrations can be designed around restricted keys that are expected to appear in client requests. In that setup, the security boundary depends heavily on API and application restrictions, quotas, and monitoring. Treating such a key as if it were an invisible server secret is misleading. Conversely, copying this exception to a payment-provider secret key would be dangerous.
A useful test is to open your site's network tab and inspect the outgoing request. If you can see a secret meant to authorize server-side account operations, every visitor can see it too. Move the call to a trusted backend and check whether a previous deployment exposed the key in static assets, build logs, or source maps.
How to rotate a key without breaking the app
Rotating a key means replacing it with a new one. The safest changeover is easier when the provider lets the old and new keys work for a short period. In that case, create the new key, give it only the permissions the application needs, update every application that uses it, and confirm the new key works before disabling the old one. If the provider supports only one active key, plan a coordinated switch; do not promise that the change will be interruption-free.
Your API key might be used by your website backend, a nightly scheduled job, and a reporting script. You create a replacement key and update only the website. Everything looks fine in the browser, but the nightly job still uses the old key. If you revoke that key immediately, the job fails hours later. Before the changeover, check every place the key is used, including scheduled tasks and development environments.
Some providers offer only one active key or rotate in place. In that case you need a scheduled maintenance plan, coordinated deployment, or a provider-supported dual-key transition. Do not promise zero downtime when the service does not support overlap. Record an owner and a date for removing the old value so an emergency temporary allowance does not become permanent.
If the key was exposed publicly, treat it as a possible incident, not ordinary housekeeping. Revoke or restrict it according to risk and provider capabilities, search logs for unusual usage, check charges and quotas, replace it in all applications, and remove it from current source files. Rewriting Git history may reduce casual rediscovery, but does not invalidate a key already copied by someone else. Credential revocation is the decisive containment step.
Read API errors in the right order
When a request fails, begin with the complete HTTP response, including status, provider error code, and request ID if one exists. Strip any credential value before sharing logs. Then check the environment and endpoint. A sandbox key against a production hostname can fail even though both the key and the code are individually correct.
| Response or symptom | Likely investigation | What to verify next |
|---|---|---|
| 401 or invalid credentials | Key missing, expired, revoked, wrong environment, wrong header | Compare documented header, environment, activation and key fingerprint |
| 403 or permission denied | API disabled, key restricted, scope or account policy mismatch | Enabled APIs, allowed referrers or IPs, roles and policy details |
| 429 or resource exhausted | Rate limit or quota reached | Per-minute versus daily limits, shared usage, Retry-After if present |
| Works locally, fails after deploy | Secret injection, hostname or egress restriction | Deployment variable names, staging domain, outbound IP, secret version |
| Sudden bill or usage spike | Unexpected traffic or compromised key | Usage metrics by key, service, project and time; rotate or revoke as needed |
The table is a diagnosis starting point, not a universal status-to-cause mapping. Some APIs return 403 for quota denial and some use 400 for malformed or unauthorized requests. Read the response body first, then compare it to the provider's reference. A generic retry loop is particularly poor treatment for a revoked credential: it creates more failed calls without correcting the problem.
A 429 response usually means too many requests, but providers enforce limits in different ways. If the response includes Retry-After, use it to decide when to try again. Otherwise follow the provider’s documented waiting time and slow down requests instead of sending them repeatedly. Also check whether you hit a short-term rate limit or exhausted a daily or monthly quota. When many customers share one backend key, their combined traffic can use up the allowance.
Another trap is silent leakage through observability. A logging library that prints full request objects might include Authorization or X-API-Key. A support screenshot can show a query-string credential. A CI job may echo environment variables while debugging. Redact sensitive headers in logging middleware, limit who can read logs, and audit build output. Moving the key into an environment variable helps only if your programs stop printing it afterward.
API keys compared with OAuth tokens and signed requests
An API key is usually easiest when a server-to-server integration needs a stable application identifier or credential and the provider explicitly supports that model. OAuth access tokens are often better when a user grants a client restricted access to their own data, with scopes and token lifetimes. Some cloud-to-cloud systems prefer short-lived workload identity or service-account credentials over long-lived static keys. The correct choice follows the provider's identity and authorization design, not a blanket claim that one method is always secure.
HMAC is a way to create a signature from a message and a shared secret. It helps the receiver check that the bytes have not changed and that the sender knows the secret. Webhook systems often use HMAC for incoming event notifications. That is a different job from sending an API key with a normal outgoing request. Do not swap these methods without checking the provider’s actual authentication design.
If you generate a random string yourself, it is not automatically a working API key. The provider must issue or register it and associate it with its own policies. Yoryantra's Random Token Generator can help create a random candidate string for a system you control, but it cannot enroll that value with Google, Stripe, or another provider. Its Request Header Builder can help you format an example request header; it does not validate provider permissions.
Check these things before your API integration goes live
First confirm the key's meaning with the provider: project identifier, account credential, or something more specialized. Restrict it to the APIs and calling context you actually need. Keep truly secret keys on the server, supply them through a secret store, and redact them from logs. Separate test and live environments, then record which deployed services consume each value.
Next run three kinds of tests: a valid request, a request without the key, and a valid key without permission for the target action. A fourth test with intentionally high request volume can help validate a rate-limit handler, but do that only in a provider-sanctioned test environment. Finally, rehearse rotation before a leak forces you to rotate under pressure.
If a call still fails, record the status, provider error code, request ID, active environment, and applied restrictions. Those details usually shorten a support investigation more than sending someone the credential itself. Never send a live secret as a debugging shortcut.