API Keys: What They Are and What They Are Not

The API key is the oldest and most misunderstood credential on the list. It is trivially easy to build, and that simplicity is a feature. It also carries a set of properties people assume it has and it does not.

What a key actually is

A key is one opaque string that the caller sends on every request. The server holds a record saying which caller that string belongs to and what it may do, so the check is a lookup.

That is the whole mechanism, and everything else follows from what it lacks.

The last row causes the most confusion. A key identifies an integration, so an API that also needs to know which end user is affected has to carry that separately, whether as a parameter, a second header or a token.

Header, not query string

This is the one hard rule in the chapter.

# Yes
GET /v1/orders
X-API-Key: rb_live_9f2a...
 
# No
GET /v1/orders?api_key=rb_live_9f2a...

A credential in the query string is written to the reverse proxy access log, kept in browser history and sent in the referrer header of the next outbound request. It travels along whenever anyone shares the URL. RFC 6750 makes the same argument about bearer tokens in URIs, and the reasoning transfers directly.

Sometimes the query string is genuinely unavoidable, usually for a webhook target or an image URL that cannot carry headers. Treat that key as a separate, narrower credential with a short life and a single permission.

Between the standard Authorization header and a custom one such as X-API-Key there is little to choose. Authorization is conventional and gets special handling by some proxies, and a custom header is unambiguous when a request already carries a user token. Browser callers need the header name in the CORS allow list either way.

Scoping is what makes a key safe to hand out

A key that can do everything is a key you cannot give to anything. Two dimensions of scoping do most of the work.

Permissions. A key that only reads cannot delete, no matter what calls it. This turns a compromised build script from an incident into a log line.

Resource restriction. A key limited to one project, tenant or account cannot reach the rest, whatever the caller asks. This is the dimension people forget, and it is the one that limits the blast radius when the permission model turns out to have a gap.

The habit to build is one key per integration instead of one key per team. Revoking a key then stops one thing and not everything, and the last-used timestamp tells you whether that integration is still alive.

Rotation is a mechanism, not an intention

Every organisation intends to rotate keys, and the ones that manage it have built one thing, namely support for two live keys at once.

Without overlap, rotation is a coordinated outage. Somebody has to revoke the old key and deploy the new one at the same instant across every consumer, so it gets postponed until an incident forces it.

With an overlap in place, rotation becomes a routine nobody dreads. Issue the new key, let consumers adopt it, watch the old key's last-used timestamp go quiet, and then revoke it.

Three supporting details make the difference.

Expiry dates. A key with an expiry produces a warning before it becomes an incident. A key with none outlives the integration it was created for.

Last-used tracking. This is what tells you a key is safe to revoke, and it is also how you find the keys nobody remembers issuing.

Show the key once. A key the server can read back is a key that can be exfiltrated from the server. Store a hash, display the value once at creation, and make people generate a new one when they lose it.

Rate limits belong per key

A rate limit keyed to the IP address punishes everyone behind a shared address, which today means an office, a cloud provider region or a mobile carrier. Once you have per-key identity, use it.

Per-key limits also give you something a global limit cannot. You see one integration misbehaving without it affecting the others. That signal is usually the first sign of a retry loop somebody deployed by accident.

Detecting a leaked key

Keys leak sooner or later, and most often they leak into a public repository. Two cheap measures reduce the damage.

Give keys a recognisable prefix. A key that starts with a distinctive marker can be found by secret scanners, including the ones that scan public repositories and notify the issuer. A key that looks like a random base64 blob cannot.

Alert on impossible use. A key issued to a build pipeline that suddenly calls from a residential address is worth a notification. So is one that was quiet for a month and then starts enumerating.

In Routebase

Two things need separating here, because both are called API keys.

The keys your API uses. In an environment's authentication configuration, the API Key type sends a key as either a header or a query parameter, with the key name entirely up to you. The value accepts a {{VARIABLE}} placeholder resolved from the environment's variables, so the key lives in a secret variable and the tests reference it. The same configuration works at suite and case level, and in a security persona.

The keys Routebase itself issues. Under Settings, an API key gives machines access to your organisation for CI pipelines, the CLI and AI agents over MCP. Each key is either full access or scoped to individual permissions, and every selected permission can additionally be restricted to a single project. A key restricted that way cannot touch the rest of the organisation, whatever the caller asks it to do.

The keys Routebase issues carry every practice described above. They start with a recognisable prefix, and the full value is shown exactly once at creation and never again. The list then shows only the prefix and the last-used timestamp, and an expiry is chosen at creation from never through to a year. Permissions can be edited later without re-issuing the key, and revoking one moves it to a separate list so the audit trail survives.

See Project Auth for the scheme your API uses, API Keys for the keys Routebase issues, and MCP Authentication for how scopes gate what an agent can even see.