API Authentication: Methods and Trade-offs

Every API request that is not public has to answer one question before anything else happens. Who is asking, and API authentication is how the request answers it. The methods that answer it look very different from each other, and almost all of the difference comes down to three properties.

Where the credential travels, what the server has to know to validate it, and how fast you can take it away again.

This guide covers every method you are likely to meet, including the ones that predate the modern stack and the ones no tool sets up for you. Each chapter says what the method is for, where it goes wrong, and how to configure it in practice. Every security claim carries the RFC it comes from, because a confident wrong answer in an authentication guide is expensive.

Authentication is not authorization

The distinction sounds pedantic and it is the source of the most common serious flaw in APIs.

Authentication establishes identity, and its failure mode is a 401. Authorization decides what that identity may do, and its failure mode is a 403.

An endpoint that checks the first and forgets the second is the pattern behind broken object level authorization, which sits at the top of the OWASP API Security Top 10 from 2023. The caller is genuinely who they say they are, and they are reading somebody else's record.

Everything in this guide is about the first question. The second one is covered in testing authentication, because the only reliable way to know your authorization works is to send two identities at it.

Where the credential travels, and why it matters

Location	Example	What to know
Authorization header	Bearer eyJ…	The default for good reasons, because it is not logged by default and not cached
A custom header	X-API-Key: …	Equivalent in practice, and it needs a CORS entry for browser callers
Query string	?api_key=…	Lands in access logs, browser history, referrer headers and shared URLs
Cookie	Set-Cookie: session=…	Sent automatically by browsers, both the feature and the CSRF risk
Request body	{"token": "…"}	Rare, awkward to cache and awkward to proxy, and it rules out GET

The query string row is the one that causes real incidents. A credential in a URL is also in the reverse proxy log, in the browser history and in the referrer header of the next outbound link. It ends up in the support ticket where somebody pasted the URL. RFC 6750 says exactly this about bearer tokens in URIs, and the reasoning applies to keys too.

Transport is a precondition, not a method

None of these schemes protect the credential in transit. TLS does that, and without it every method here is equivalent to shouting the password.

Two specific consequences follow. Basic authentication is not "insecure" in the sense people usually mean, because it is exactly as secure as the channel underneath it. And a token that has travelled over plain HTTP once should be treated as compromised, because you have no way to know whether it was.

Three situations, and what fits each

Almost every real decision is one of these three.

A machine calling a machine. A background job, a partner integration, a service in your own estate. There is no user, so there is nothing to delegate. An API key or the client credentials grant covers it, and the grant wins where you want short-lived tokens and central revocation.

Acting on behalf of a user. A third-party application wants to read a user's data with their permission. This is what OAuth 2.0 was designed for, and authorization code with PKCE is the current answer. Add OpenID Connect when you also need to know who the user is and not only what they permitted.

A browser talking to your own API. The credential has to survive a page reload and it has to be unreachable from injected script. A cookie with HttpOnly, Secure and a sensible SameSite usually beats a token in local storage, which mutual TLS, cookies and custom HMAC covers.

The map of methods

Method	Built for	Chapter
API keys	Identifying a calling application	API keys
HTTP Basic	Sending a username and password over TLS	Basic and Digest
HTTP Digest	Password authentication without sending the password	Basic and Digest
Bearer tokens	Carrying an issued token	Bearer tokens and JWT
JSON Web Tokens	Carrying signed claims the server can validate without a lookup	Bearer tokens and JWT
OAuth 2.0	Delegated access without sharing the password	OAuth 2.0 grants
OpenID Connect	Identity on top of OAuth 2.0	OpenID Connect
OAuth 1.0, AWS SigV4, Hawk, NTLM	Signing the request, not sending a token	Signature-based and legacy
Mutual TLS	Certificates as identity at the transport layer	Mutual TLS and friends
Session cookies	Browser sessions against your own API	Mutual TLS and friends

Two further chapters cover the practice, not the methods. Designing authentication into your OpenAPI spec is how consumers and agents learn which scheme an endpoint expects, and setting it up in Routebase is the end-to-end configuration walkthrough.

The short version of the decision

The full table lives in choosing a method, and this is the part most people need.

• Machine to machine, inside your control: an API key, scoped and rotatable.
• Machine to machine, where you want short-lived credentials: OAuth 2.0 client credentials.
• On behalf of a user, any client type: OAuth 2.0 authorization code with PKCE, per RFC 7636.
• You also need the user's identity: OpenID Connect.
• Browser session against your own API: a cookie with HttpOnly, Secure and SameSite.
• Very high assurance between known parties: mutual TLS, usually alongside one of the above.

What should not be on that list is a custom scheme you designed. RFC 9700 documents what the OAuth working group has learned across two decades, and a scheme written in an afternoon has not learned any of it.

In Routebase

Routebase carries a catalogue of ten authentication schemes plus none, and the same catalogue appears everywhere authentication is configured. That means environments, test suites, individual test cases and security personas all use the identical editor, so a scheme you set up once behaves the same wherever you apply it.

The catalogue covers Basic, Bearer and API Key, where the key travels in a header or a query parameter under a name you choose. It also covers OAuth 2.0 with four grant types, OAuth 1.0, JWT Bearer signed from a secret or a private key, Digest, AWS Signature V4, Hawk and NTLM. Every credential field accepts a {{VARIABLE}} placeholder resolved from the environment's variables, so the scheme lives in the configuration and the secret lives in a secret variable.

Read on for the method you need, or jump straight to setting up authentication in Routebase. The product documentation for the configuration surface is Project Auth. What happens after the token is valid, meaning whether this caller may have this object, is the subject of the API security guide.