Bearer-token authentication and state

Direct Answer

In bearer-token authentication, a client presents a secret token—normally in the Authorization header—and possession is enough to use it, so TLS and leak prevention are essential. The design is not inherently stateless: opaque tokens require server-side lookup, and JWT systems often keep refresh, revocation, or account state even when access-token signatures are verified locally.

Deep Dive & Architecture

An opaque access token should be generated with enough randomness that guessing is infeasible. Store only a cryptographic hash, just as a password-reset system avoids storing the usable secret. On every request, hash the presented token and find an active record. The record can hold expiry, scopes, user, client, and revocation time. This adds a lookup but gives the server immediate control over one credential.

A signed JWT contains claims such as issuer, audience, subject, and expiration. A resource server validates the allowed algorithm, signature, issuer, audience, time claims, and any required scope before trusting it. Base64url-encoded claims are readable; signing prevents undetected modification but does not encrypt them. Sensitive private data does not belong in ordinary signed claims.

Local JWT validation can remove a central access-token lookup, yet the broader system often remains partly stateful. A user may be suspended after the token was issued, roles may change, refresh tokens need rotation and reuse detection, and emergency logout may require a deny list or token-version check. If the API skips all current checks, it consciously accepts access until the short-lived token expires.

The client also changes the threat model. Page URLs are a poor token transport because URLs commonly enter history and logs. Browser local storage is readable by injected script; an HttpOnly cookie prevents normal JavaScript reads but is sent automatically and therefore needs CSRF-aware design. Native applications should use platform-protected credential storage. Every bearer flow requires HTTPS.

On failure, an absent, expired, malformed, or unverifiable credential normally produces 401 with an appropriate authentication challenge. A valid identity that lacks permission produces 403. Logs may record a token identifier or request correlation value, never the bearer secret itself. Good token design combines short lifetime, narrow audience and scope, safe storage, rotation, revocation policy, and explicit authorization.

A threat model should name who issues the token, which service accepts it, how clock skew is handled, and what happens after theft. Those answers determine lifetime, audience, storage, and revocation; choosing JWT first and discovering these requirements later reverses the design process.

Code Example

require "digest"

class ApiController < ActionController::API
  before_action :authenticate_token!

  private

  def authenticate_token!
    scheme, secret = request.authorization.to_s.split(" ", 2)
    return head :unauthorized unless scheme&.casecmp?("Bearer") && secret

    digest = Digest::SHA256.hexdigest(secret)
    token = AccessToken.active.find_by(token_digest: digest)
    return head :unauthorized unless token

    @current_user = token.user
  end
end

This opaque-token design deliberately performs a database lookup, so it is revocable and stateful rather than inherently stateless.

Common Mistakes & Pitfalls

Calling all token authentication stateless or treating a signed JWT as encrypted.