API Authentication & Authorization: A Developer Guide

API authentication is the discipline most engineering teams believe they have solved and most pentest reports demonstrate they have not. The conflation of authentication with authorization, JWT bearer tokens without revocation strategies, shadow endpoints discovered only by attackers, and scattered object-level access checks have produced a decade of API breaches with the same root cause. This guide covers the five mechanisms developers actually meet, the JWT-vs-opaque-token choice, OAuth 2.1 in 2026, mTLS for internal services, and the BOLA/BFLA distinction that separates a logged-in user from an authorized one. It pairs with our OWASP API Security Top 10 hub and assumes a microservices-aware reader who has shipped at least one service that talks to another over HTTPS.

Why API Auth Is Different From Web Auth

The patterns developers learned for web authentication — session cookies, CSRF tokens, same-origin policy, browser storage — encode assumptions that do not hold for APIs. A web application has a browser with an isolated cookie jar, CSRF tokens in hidden form fields, and SameSite=Lax honored by the user-agent. None of this is true for API traffic, and most API auth bugs trace to engineers who carried web assumptions across the boundary.

An API client is generally a process — a mobile app, an SPA, a backend service, a CI job, a partner integration. No browser context, no cookie jar, no CSRF protection for free. The token was either embedded in the client, provisioned through token exchange, or relayed from another service. Replace "the user is logged in" with "this request carries a credential — what does the credential prove, and is the operation authorized for the principal it identifies?"

Scale differs too. An API gateway authenticates every request; a service mesh authenticates every internal call. A typical microservices deployment processes millions of auth operations per minute — qualitatively different from session management at web scale.

Threat model differs as well. Browsers ship with same-origin policy, CSP, secure cookies, and a human user. API clients have none of that. The credential sits in a config file, an environment variable, a key vault, or process memory. The attacker does not phish a human; they read a config file or compromise a CI runner. Short credential lifetimes plus rotation discipline replace the browser-side defenses web auth gets for free.

The Five Authentication Mechanisms

API authentication in production reduces to five mechanisms, alone or in combination. Each fits a specific shape of client and traffic, and each has a specific failure mode when used outside its fit.

API keys. A long opaque string in a header, identifying the calling application or partner, not a user. Appropriate for server-to-server traffic between trusted partners and internal tools where the calling identity is the system. The failure modes are well-known: keys leak into git history, client-side bundles, logs, and support tickets. The mitigation is rotation, scope restriction, and inventory. api key security is a discipline of operations, not cryptography.

Mutual TLS. Both endpoints present X.509 certificates and verify each other at the TLS layer. mTLS fits internal service-to-service traffic where both sides are under the same operational control and a service mesh or PKI provisions certificates automatically. The advantages are strong identity binding, no in-flight credentials to leak, and integration with zero-trust. The cost is the operational tax of running PKI.

OAuth 2.1 + OIDC. The standard for delegated authentication across organizational boundaries. OAuth 2.1 (consolidated 2024) handles authorization grants; OIDC layers identity assertions on top — the oauth 2 vs openid connect distinction matters because OAuth authorizes API access while OIDC adds the verifiable identity claim. Together they fit user-facing applications where a third-party identity provider authenticates the user and your API trusts the assertion. Failure modes are documented in our OWASP A07 Authentication Failures guide. OAuth done right is excellent; OAuth hand-rolled against PKCE-less flows is a recurring CVE generator.

JWT bearer tokens. A signed token format carrying claims (user ID, scopes, expiry) verified by the resource server without a network call. Widely deployed as the access-token format inside OAuth flows and for direct service-to-service auth. Stateless verification is the key property — and the architectural constraint, since revocation cannot be implemented without giving it up.

Session cookies for browser-API hybrids. When the API is consumed primarily by a browser SPA on the same first-party domain, session cookies remain defensible — HttpOnly, Secure, SameSite=Strict or Lax, short-lived. The pattern does not fit when the API is multi-tenant, when third-party clients are anticipated, or when mobile clients consume the same endpoints.

The first mistake teams make is choosing one mechanism for every traffic class. APIs typically need at least two — OAuth for user-facing requests, mTLS for internal service-to-service — and the auth gateway routes accordingly. The second mistake is choosing JWT because it is fashionable when an opaque token would have served. The third is using API keys for human users.

Identity-protocol selection sits underneath these mechanism choices. The OIDC vs OAuth question — whether to extend a pure authorization framework with an identity layer — typically resolves toward OIDC the moment the API needs to know who the user is rather than just whether a presented token is valid. In B2B integrations the equivalent SAML vs OpenID decision comes up earlier and harder: legacy enterprise IdPs ship SAML, greenfield SSO standardizes on OIDC, and any gateway that bridges the two becomes its own attack surface and operational burden.

JWT vs Opaque Tokens — The Architectural Choice

JWT is not an authentication mechanism. It is a token format — a signed, base64-encoded JSON payload — that can carry credentials issued by any authentication mechanism. Choosing JWT versus an opaque random token is architectural, and the consequences ripple through revocation, rotation, claim management, and incident response. The jwt vs opaque tokens trade-off is the most common architectural debate in API auth design.

JWT verification is stateless. The resource server has the issuer's public key and validates the signature locally. No network call per request. Latency is low, the issuer is not a bottleneck, and the resource server can serve traffic during issuer downtime — what made JWT popular for high-throughput APIs.

Statelessness has a cost. A JWT is valid until expiry, regardless of whether the user logged out, the account is disabled, or the token was compromised. Revoking requires accepting the remaining lifetime as the delay, maintaining a denylist (reintroducing state), or keeping lifetimes very short (5-15 minutes) and using refresh tokens. The third is the standard 2026 pattern — but it means the system is no longer truly stateless, since refresh-token tracking needs server-side state.

Opaque tokens are stateful by design. A random string that means nothing without a lookup against the issuer. Verification requires a network call (often cached); revocation is a single database update. The performance cost is tolerable with caching. Teams operating small-to-medium APIs often find opaque tokens easier to reason about.

Claim bloat. A frequent JWT failure mode: each downstream service needs claims, each team adds them, and the token grows from 200 bytes to 8KB until HTTP header limits crack. The fix is keeping JWT claims minimal and resolving everything else through the user service on demand.

Key rotation discipline. JWTs signed with asymmetric keys (RS256, ES256) require resource servers to fetch the issuer's JWKS endpoint. Rotation requires advance publication, an overlap window where both keys are valid, and propagation to every resource server. Teams that ship JWT auth without a key-rotation plan ship a system whose signing key cannot be rotated without coordinated downtime.

The "alg:none" hall of shame. The JWT specification permits an alg: none token — unsigned, valid by virtue of having declared itself unsigned. Multiple library implementations historically accepted these by default. The class is fixed in modern libraries but persists in older deployments and hand-rolled verification code. The defense is an explicit allowlist of acceptable algorithms in every verification call:

// Node.js with the jose library
import { jwtVerify } from 'jose'

const allowedAlgs = ['RS256', 'ES256']

const { payload } = await jwtVerify(token, publicKey, {
  algorithms: allowedAlgs,  // explicit allowlist
  issuer: 'https://auth.example.com',
  audience: 'api.example.com',
})

if (!payload.sub) throw new Error('Missing subject claim')

The algorithms option is the critical line. Without it, the library accepts any algorithm the token declares — including none in older versions, including HMAC variants if an attacker swaps algorithms and signs with the public key as the HMAC secret (the classic algorithm-confusion attack). The same pattern applies to PyJWT, Java JWT libraries, and .NET token handlers.

OAuth 2.1 in 2026

OAuth 2.1, the consolidated 2024 specification, removes the parts of OAuth 2.0 that history demonstrated were unsafe and codifies the patterns the security community had already converged on. Any new OAuth deployment in 2026 against the old specification with implicit or password grants is implementing a deprecated standard.

Deprecated grants. The implicit grant — access token returned to the browser in the URL fragment — is gone. The token leaks through browser history, the Referer header, and the JavaScript context. SPAs use the authorization-code grant with PKCE instead. The resource-owner password credentials grant is also gone; it defeats the purpose of OAuth, which is to keep the password out of the application's hands.

PKCE for all clients. Proof Key for Code Exchange — originally an extension for public clients — is mandatory for all clients in OAuth 2.1, including confidential ones. The client generates a random verifier, hashes it to a code challenge, sends the challenge with the authorization request, and includes the verifier in the token exchange. The authorization code is bound to the verifier; an attacker who intercepts the code cannot exchange it. PKCE adds two dozen lines and closes the authorization-code interception class entirely.

// TypeScript — OAuth 2.1 PKCE flow (browser SPA)
function generateVerifier(): string {
  const arr = new Uint8Array(32)
  crypto.getRandomValues(arr)
  return base64urlEncode(arr)
}

async function generateChallenge(verifier: string): Promise<string> {
  const data = new TextEncoder().encode(verifier)
  const digest = await crypto.subtle.digest('SHA-256', data)
  return base64urlEncode(new Uint8Array(digest))
}

const verifier = generateVerifier()
const challenge = await generateChallenge(verifier)
sessionStorage.setItem('pkce_verifier', verifier)

// Step 1: redirect user to authorization endpoint
const authUrl = new URL('https://auth.example.com/authorize')
authUrl.searchParams.set('response_type', 'code')
authUrl.searchParams.set('client_id', CLIENT_ID)
authUrl.searchParams.set('redirect_uri', REDIRECT_URI)
authUrl.searchParams.set('scope', 'openid profile api:read')
authUrl.searchParams.set('code_challenge', challenge)
authUrl.searchParams.set('code_challenge_method', 'S256')
window.location.href = authUrl.toString()

// Step 2: exchange the code returned in the redirect
const code = new URLSearchParams(window.location.search).get('code')
const storedVerifier = sessionStorage.getItem('pkce_verifier')

const tokenResponse = await fetch('https://auth.example.com/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code,
    redirect_uri: REDIRECT_URI,
    client_id: CLIENT_ID,
    code_verifier: storedVerifier!,  // proves we initiated this flow
  }),
})

const { access_token, refresh_token } = await tokenResponse.json()

Refresh-token rotation. A refresh token in OAuth 2.1 is single-use. Each exchange issues a new one and invalidates the old. If an attacker has stolen a refresh token, the legitimate client's next refresh fails and the authorization server detects the duplicate use and revokes the entire family. Theft becomes detectable rather than silent.

DPoP — sender-constrained tokens. Demonstration of Proof-of-Possession (RFC 9449) binds an access token to a specific client key. The client signs each request with the bound key; the resource server verifies both. An attacker who steals the bearer token cannot replay it from a different client. Auth0, Okta, Keycloak, and AWS Cognito all support DPoP on the issuer side, and libraries for Node, Python, Java, and Go ship verification.

mTLS for Internal APIs

Mutual TLS for internal service-to-service traffic is the standard 2026 pattern in zero-trust deployments. Both services present certificates issued by an internal CA, both verify the other, and the TLS handshake establishes mutual identity before any application traffic flows. Application code can trust that the connecting service is who its certificate identifies.

The driver for adoption is the collapse of network-trust-based authentication. The "we trust the network because it is internal" model died with zero-trust, with the recognition that lateral movement is the dominant attack pattern, and with the realization that "internal" is no longer a coherent boundary in deployments spanning regions, clouds, and partner integrations. mTLS replaces network-trust assumptions with cryptographic identity.

The cost is the operational tax of running PKI. Service meshes (Istio, Linkerd, Consul Connect) automate issuance, distribution, and rotation; SPIFFE/SPIRE provides identity primitives; cert-manager handles the leaf-certificate lifecycle in Kubernetes. Teams that adopt mTLS without one of these automation layers spend weeks per quarter on certificate fire drills and eventually retreat.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: payments-api-cert
  namespace: payments
spec:
  secretName: payments-api-tls
  duration: 720h        # 30 days
  renewBefore: 168h     # renew 7 days before expiry
  subject:
    organizations:
      - example.com
  commonName: payments-api.payments.svc.cluster.local
  dnsNames:
    - payments-api.payments.svc.cluster.local
  issuerRef:
    name: internal-ca-issuer
    kind: ClusterIssuer
  privateKey:
    algorithm: ECDSA
    size: 256
    rotationPolicy: Always   # new key on every renewal

The renewBefore window matters. A certificate that renews seven days before expiry has six days of safety margin if the renewal pipeline breaks. rotationPolicy: Always ensures key material rotates on each renewal — without it, the same private key persists across cert lifetimes and a key compromise survives every renewal. HashiCorp Vault's PKI engine provides the same primitives outside Kubernetes.

mTLS authentication and authorization are separate. The certificate proves who is connecting; it does not prove what the service is allowed to do. Service-mesh policies (Istio's AuthorizationPolicy, Linkerd's policy CRDs) layer authorization on top — service A can call service B's /orders, but not /admin. mTLS for authentication plus mesh policies for authorization is the standard zero-trust internal-API pattern.

Authorization Is Not Authentication — The BOLA/BFLA Distinction

The single most expensive class of API bug in the last decade is the conflation of authentication with authorization. The application checks that the request carries a valid token; it does not check that the principal the token identifies is permitted to operate on the specific resource. The attacker, holding a legitimate token for their own account, modifies the URL or request body to reference another user's resources and the API returns them.

OWASP API Security Top 10 names two variants. Broken Object Level Authorization (BOLA, formerly IDOR) — a request includes a resource identifier the application uses without checking that the authenticated principal owns it. Broken Function Level Authorization (BFLA) — a request invokes a function (typically administrative) the principal is not permitted to invoke; the application checks authentication but not function-level authorization. bola prevention and bfla prevention are the two disciplines every API endpoint owes its callers.

The vulnerable BOLA pattern in five lines:

// Express.js — BOLA: trusts userId from URL, not from token
app.get('/api/users/:userId/orders', authenticate, async (req, res) => {
  const orders = await db.orders.findMany({
    where: { userId: req.params.userId }   // attacker controls this
  })
  res.json(orders)
})

The authenticate middleware verifies the JWT and attaches req.user. The route handler trusts req.params.userId from the URL path. An attacker authenticated as user 42 calls /api/users/43/orders and receives user 43's orders. The fix is to derive the user identifier from the authenticated principal:

// Fixed: derive userId from the verified token
app.get('/api/users/me/orders', authenticate, async (req, res) => {
  const orders = await db.orders.findMany({
    where: { userId: req.user.sub }   // from the verified JWT claim
  })
  res.json(orders)
})

// For admin endpoints that take a target userId, an explicit check
app.get('/api/admin/users/:userId/orders', authenticate, async (req, res) => {
  if (!req.user.roles.includes('admin')) {
    return res.status(403).json({ error: 'forbidden' })
  }
  const orders = await db.orders.findMany({
    where: { userId: req.params.userId }
  })
  res.json(orders)
})

Two patterns: client-facing endpoints derive the user ID from the token; admin endpoints take an explicit user ID and require an explicit role check. The application never trusts a client-supplied identifier as the authorization target. The pattern is identical to the discipline behind Broken Access Control (web A01); BOLA and BFLA are the API-shaped expressions of the same underlying flaw.

Peloton 2021 is the canonical example: an endpoint exposed user profile data and trusted a userId parameter without checking whether the requester was permitted to retrieve it — three million accounts enumerable by iterating user IDs. Optus 2022 in Australia followed the pattern at API scale: customer records keyed by sequential identifiers were returned by an authenticated endpoint without verifying ownership. T-Mobile's 2023 API misuse incident — 37 million customer records — traced to the same class. HackerOne's public BOLA disclosures in 2024-2025 read like a tour of every major SaaS provider; the pattern is universal because the discipline of "verify ownership on every endpoint" is universal in its absence.

Centralized Authorization Patterns

The fix for BOLA and BFLA is conceptually simple — every endpoint performs an explicit authorization check — and operationally hard, because consistent application across hundreds of endpoints requires architectural support, not code-review heroics. The 2026 answer is centralized authorization: a policy engine the application consults rather than scattering checks through resolver code.

Sidecar PDP — Open Policy Agent. OPA is the dominant policy as code engine for cloud-native authorization. Policies are written in Rego, distributed as bundles, and evaluated by an OPA sidecar the application queries with a JSON request describing the decision. Application code shrinks to "ask OPA whether this principal can perform this action on this resource"; the policy lives in version-controlled files reviewed by security and platform teams.

# Rego policy — object-level authorization for orders
package authz.orders

default allow = false

# Owner can read their own orders
allow {
  input.action == "read"
  input.resource.type == "order"
  input.resource.owner_id == input.principal.id
}

# Customer support role can read any order in their tenant
allow {
  input.action == "read"
  input.resource.type == "order"
  input.principal.roles[_] == "support"
  input.resource.tenant_id == input.principal.tenant_id
}

# Admin can read any order
allow {
  input.action == "read"
  input.resource.type == "order"
  input.principal.roles[_] == "admin"
}

The application calls OPA with the principal (from the verified JWT), the action, and the resource; OPA returns allow: true or false. The policy is testable in isolation, auditable as code, and changeable without redeploying the application.

AWS Cedar. Amazon's policy language, open-sourced in 2023, is the alternative for AWS-heavy deployments and teams that prefer Cedar's more constrained syntax. Cedar is fit for authorization decisions; Rego is fit for arbitrary policy decisions including authorization. The question is whether your authorization needs are bounded enough that Cedar's tighter scope is an advantage.

In-process policy engines. The OPA Go SDK, Cedar's native libraries, and Casbin evaluate policies inside the application process. Lower latency and operational simplicity; policy distribution becomes the deployment problem.

Gateway vs service-level authorization. The honest answer is both. Gateway authorization (Kong, Tyk, AWS API Gateway, Apigee, Envoy with ext_authz) handles authentication, scope checks, and rate limits at the edge. Service-level authorization handles the BOLA cases the gateway cannot reason about because it does not know resource ownership. A program that puts all authorization at the gateway ships BOLA bugs; a program that puts all of it at the service level loses the rate-limit and scope-filter benefits of the edge.

The Inventory Problem

You cannot secure what you do not know exists. The most underappreciated API security problem in 2026 is inventory — the gap between the endpoints the security team believes run and the endpoints actually deployed and reachable. Every audit uncovers shadow APIs the architecture diagrams do not list, deprecated endpoints still reachable years after being marked for removal, and internal endpoints (/admin/v1/internal/...) never intended to be exposed but are.

The causes are mundane. A team ships a new version and leaves the old one running indefinitely without patches. A debug endpoint exposed in staging becomes production through configuration drift. A partner-specific endpoint persists after the customer churns, with auth checks removed for some long-forgotten support ticket. Each is small in isolation; in aggregate they are the surface attackers exploit.

The 2026 toolchain is mature. Salt Security, Noname Security, and Akamai API Security run as traffic mirrors that observe production traffic, classify endpoints, identify auth patterns, and flag drift between observed and documented APIs. Postman's API governance integrates with CI/CD to catch undocumented endpoints before they ship. AWS API Gateway logging combined with structured service-layer logs produces an authoritative catalog from observed traffic. The choice matters less than running one continuously and reconciling observed against intended inventory.

Durable hygiene is automation: every deployment writes its API specification to a central registry, every gateway logs every endpoint, every traffic-observation tool feeds the same registry, and a weekly job reconciles the sources and flags discrepancies.

Detection — Anomalous Auth Patterns

Authentication and authorization failures often produce log signatures detectable in real time, and detection is most effective built around specific anomalies rather than generic "auth errors went up" alerts.

Token reuse from multiple IPs. A bearer token is bound to its bearer; legitimate use comes from a small set of IPs. A token that suddenly appears from a new geography, or is used concurrently from two distant ones, is a strong signal of theft. The mitigation is automatic — revoke the token, force re-authentication, alert the user.

401/403 ratio spikes. Normal API traffic has a stable rate of 401 and 403 responses dominated by expired tokens and known-broken integrations. A sudden spike concentrated on a user, IP, or endpoint family is enumeration, credential stuffing, or a leaked-credential probe. Per-principal rate limits at the gateway catch the volumetric variants; alerting on the ratio catches the slow ones.

BOLA enumeration patterns. When an attacker iterates sequential resource IDs, the log signature is distinctive — a single principal making requests to /api/users/1/..., /api/users/2/..., /api/users/3/..., with mixed 200/404 responses. SIEM rules and gateway plugins detect this without full UEBA infrastructure. The Twitter 2022 API token-leak incident — a long-lived API key allowing bulk lookups against an unauthenticated endpoint — produced exactly this signature for months before detection.

Token issuance anomalies at the IDP. The authorization server sees every token issued, to which client, with which scopes. Anomalies at the issuance layer (a service principal requesting elevated scopes, a refresh-token family reused after dormancy, a client-credentials grant from a new IP) are first-mover signals. Modern IDPs (Auth0, Okta, Azure AD, AWS Cognito) expose these and integrate with SIEMs.

The Mitigation Playbook

The patterns that produce a defensible API auth posture in 2026 are knowable and have converged. The work is in applying api auth best practices consistently across the surface of your APIs.

Centralize authorization. Move authorization out of resolver code into a policy engine — OPA, Cedar, in-process equivalent. Every endpoint asks the engine; no endpoint hand-rolls the check.

Never trust client-supplied claims. User ID, tenant ID, role, entitlement — all come from the verified token, never the request body or URL. Verification is centralized in middleware that attaches the verified principal; route handlers read from the principal, not request parameters.

Machine-to-machine traffic uses mTLS. Internal service calls authenticate by certificate, not shared API key. PKI is automated through a service mesh or cert-manager. Authorization between services is enforced by mesh policies.

Gateway-level rate limits. Every endpoint gets a default per-principal limit. Sensitive endpoints (login, password reset, admin) get tighter limits. Limits are enforced before the request reaches the application, so an authenticated attacker cannot enumerate identifiers at credential-attack speed.

JWT algorithm allowlists, everywhere. Every verification call passes an explicit list of acceptable algorithms — typically one, occasionally two during rotation. Closes algorithm-confusion and alg:none.

Key rotation discipline. Signing keys, CAs, and HMAC secrets all have rotation schedules and tested procedures. Rotation is a scheduled operation, not an emergency. This connects to the broader cryptographic-failures discipline that prevents weak key management from undermining strong protocols.

Token binding through DPoP or mTLS-bound tokens. Where the threat model includes bearer-token theft, bind the token to a client-held key so theft alone is not enough.

API inventory hygiene. Automated inventory reconciling deployed endpoints, documented endpoints, and observed traffic. Discrepancies are reviewed weekly. Shadow endpoints are documented or removed.

Defense-in-depth with SSRF mitigation. mTLS on internal endpoints is part of the defense against SSRF (A10). An SSRF that reaches an internal endpoint requires both network reachability and authentication; mTLS removes the second prerequisite when the first fails.

Training that targets the developer's stack. Knowing about BOLA in the abstract does not prevent an engineer from writing req.params.userId into a database query. Pulling the user ID from the verified token, asking the policy engine before returning data, using algorithm allowlists — those become reflexes through deliberate practice in the developer's actual stack.

Closing: Authentication Is the Easy Half

The teams that ship API auth well in 2026 share a posture: they treat authentication as solved and authorization as the hard part. Authentication is choosing one of five mechanisms, configuring it correctly, rotating keys on a schedule, and verifying tokens with explicit algorithm allowlists. Authorization is the cumulative discipline of every endpoint, every resolver, every database query asking the right question — does this principal have the right to operate on this specific resource, in this specific way, right now? — and answering it through a centralized policy engine rather than scattered hand-rolled checks.

OWASP API Security Top 10 placed BOLA at #1 in 2019 and again in 2023 not because object-level authorization is intrinsically harder than other security disciplines but because it is the discipline most consistently absent from API code in production. Teams that closed their BOLA surface did it through architectural support — policy engines, principal-from-token middleware, gateway enforcement — not individual heroics.

Every API breach in the last five years has produced the same retrospective. Authentication was implemented; the JWT signature was validated. Authorization was implicit, scattered, and inconsistent. The fix was always the same — centralize, verify ownership, never trust the client claim. Teams that internalize the patterns before the incident are the ones that do not have one to recover from.