API Authentication: Establishing Caller Identity and Authority

An API receiving a request needs to know who or what is calling before it can protect private data or privileged actions.

API authentication validates credentials that represent a caller identity; authorization then decides what that identity may do.

An API credential is valuable authority. Anyone who obtains a usable credential may act within its permissions until it expires or is revoked.

A concrete example: a mobile access token

After a user signs in, a mobile application receives a short-lived access token.

It calls:

GET /account
Authorization: Bearer eyJ...

The API validates:

• Signature or token lookup
• Issuer
• Audience
• Expiration
• Required authentication context

It then authorizes the token's subject to read that account.

Decoding token text without validating it proves nothing.

Authentication and authorization are separate

Authentication establishes:

caller = customer 1042

Authorization evaluates:

may customer 1042 read order 9001?

A valid token does not grant every operation.

Authorization can depend on:

• Resource ownership
• Role
• Scope
• Tenant
• Current account state
• Time
• Transaction amount

Enforce authorization at every trusted operation, not only once at login.

API keys

An API key is a secret value identifying a caller or project.

It is simple for:

• Server-to-server integration
• Usage tracking
• Development tools
• Low-complexity public APIs

Limitations:

• Often long-lived
• Commonly broad
• Easy to copy
• May identify an application rather than a user

Keys should be random, scoped, stored hashed where verification permits, rotated, and never placed in public client code.

A browser or mobile app cannot keep an embedded shared secret from its user.

Bearer tokens

A bearer token grants access to whoever presents it.

It may be:

• Opaque random value looked up by the server
• Signed token containing claims

Bearer tokens must be protected:

• Use HTTPS.
• Avoid URLs and logs.
• Keep lifetime short.
• Limit scope and audience.
• Store safely.

Proof-of-possession designs bind a token to a key or connection, reducing replay after theft, but add protocol complexity.

Signed tokens

A signed token can contain:

• Subject
• Issuer
• Audience
• Expiration
• Scopes
• Authentication method

The API verifies the signature with a trusted key.

It must also validate claims.

Common failures include:

• Accepting wrong issuer
• Ignoring audience
• Allowing unsupported algorithm
• Trusting expired tokens
• Treating unverified decoded claims as truth

Use maintained libraries and strict configuration.

Opaque versus self-contained tokens

Opaque tokens require introspection or server lookup.

Benefits:

• Immediate revocation
• Claims remain server-side
• Smaller token

Costs:

• Lookup dependency
• Added latency

Self-contained signed tokens validate locally.

Benefits:

• No per-request identity lookup
• Distributed verification

Costs:

• Revocation is harder before expiration
• Claims can become stale
• Payload is visible to the holder unless encrypted

Choose according to latency, privacy, and revocation requirements.

Session cookies

Browser APIs often use an authenticated session cookie.

Safe cookies can use:

• Secure
• HttpOnly
• Appropriate SameSite
• Narrow path and domain
• Rotation
• Expiration

Cookies are attached automatically by browsers, which creates cross-site request forgery concerns.

CSRF defenses and same-site policy are needed for state-changing operations.

Do not assume tokens in browser storage are automatically safer; script injection can expose them.

OAuth delegation

OAuth allows a user or organization to grant an application limited API access without sharing the user's password.

Roles include:

• Resource owner
• Client
• Authorization server
• Resource server

The client receives an access token with scopes such as:

calendar.read

OAuth is an authorization framework, not a user identity protocol by itself.

OpenID Connect adds standardized authentication and identity claims on top of OAuth.

Authorization code flow

For interactive applications:

1. Client redirects the user to the authorization server.
2. User authenticates and consents.
3. Client receives a short-lived code.
4. Client exchanges it for tokens.

Proof Key for Code Exchange, or PKCE, binds the exchange to the client instance and protects intercepted codes.

Native and browser applications should use current recommended flows rather than embedding a client secret they cannot protect.

Avoid deprecated flows designed for older browser constraints.

Client credentials

A service can authenticate as itself using a client-credentials flow or workload identity.

The resulting token represents the service, not an end user.

Use it for:

• Scheduled job
• Internal service
• Machine integration

Do not use one shared service identity for every application.

Separate identities enable least privilege, attribution, and targeted revocation.

When acting for a user, preserve delegated user context where the downstream decision requires it.

Workload identity

Cloud and orchestration platforms can assign identities to running workloads.

The application exchanges platform-provided proof for short-lived credentials.

Benefits:

• No static secret in configuration
• Automatic rotation
• Identity tied to deployment
• Fine-grained policy

The platform's metadata or identity endpoint must be protected from untrusted code and server-side request forgery.

Workload identity reduces secret management but increases dependence on platform identity configuration.

Mutual TLS and client certificates

With mutual TLS, both client and server present certificates.

It provides strong machine authentication and encrypted transport.

Uses include:

• Partner integrations
• Service meshes
• High-assurance machine communication

Operational challenges include:

• Certificate issuance
• Rotation
• Revocation
• Trust stores
• Mapping certificate identity to authorization

mTLS authenticates the connecting workload. It may still need user-level identity and application authorization.

Signed requests

Some APIs sign each request using a secret or private key.

The signature may cover:

• Method
• Path
• Selected headers
• Body hash
• Timestamp
• Nonce

This can protect integrity and prove possession, even through some intermediary paths.

Canonicalization must be exact, and replay protection is essential.

Use established provider schemes rather than inventing a signing protocol.

Scopes and least privilege

Scopes express coarse permissions:

orders.read
orders.write

They limit token authority.

Scopes do not replace resource-level authorization.

A token with orders.read may still read only orders belonging to its tenant.

Avoid one universal admin scope when narrower operations are possible.

Consent screens should explain permissions in language users understand.

Audience and issuer

A token should name:

• Who issued it
• Which API should accept it

Without audience checks, a token issued for one service may be replayed to another service that trusts the same signer.

Without issuer checks, an attacker may supply a token from an untrusted authority.

Validation configuration is part of the trust boundary.

Key discovery endpoints also need trusted URLs and caching behavior.

Expiration, refresh, and revocation

Short-lived access tokens reduce the window after theft.

Refresh tokens can obtain new access tokens and therefore deserve stronger protection, rotation, and reuse detection.

Revocation may occur when:

• User signs out
• Device is lost
• Password changes
• Permission is removed
• Compromise is suspected

Self-contained access tokens may remain valid until expiration unless the API uses revocation lists or introspection.

Design lifetime from risk and operational needs.

Credential storage

Server credentials belong in a secret manager or workload identity system.

Browser credentials need protection against:

• Cross-site scripting
• CSRF
• Malicious extensions
• Shared devices

Mobile applications can use platform secure storage, but a compromised device can still expose active sessions.

Never log:

• Authorization headers
• Session cookies
• Refresh tokens
• Full API keys

Redaction should happen before data enters broad logging pipelines.

Knowledge check

1. Why does a valid token not automatically authorize access to every resource?
2. Why should an API key not be embedded in a public mobile app?
3. What tradeoff separates opaque and self-contained tokens?
4. How does OAuth differ from OpenID Connect?
5. Why must an API validate both token issuer and audience?

The one idea to remember

API credentials represent authority. Authenticate with established protocols, validate every trust claim, scope credentials narrowly, keep them short-lived and protected, and perform resource-level authorization after identity is established.