API token authentication sequence
Client obtaining and using bearer tokens for API requests.
APIs need a way to know which client is asking and whether they're allowed. This template shows the standard pattern: the client asks for a token by proving who they are, uses that token to call the API, and when it expires, exchanges a refresh token for a fresh one without re-authenticating. It's the foundation of nearly every modern API's security.
The actor is a client — a mobile app, a backend service, a third-party tool — because the flow is identical whether it's code or a user. The two participants are the API server (which guards the resources) and a separate auth service (which issues tokens). Separating them makes it clear that authentication is a distinct concern.
When to use this template
- Designing a new API — decide on access tokens vs. API keys, token lifetime, and refresh strategy before you write the security code.
- Onboarding API consumers — show partners how to request tokens and include them in every request; this diagram is often clearer than prose in your API docs.
- Security review — auditors expect to see token issuance, expiration, and refresh in this order. Showing it visually answers most of their questions up front.
How to adapt it
Customize the Auth Service name to match your system — Keycloak, Auth0, your custom service — and adjust the token lifetime and refresh strategy:
- Longer-lived tokens — if all clients are backend services on secure networks, extend token lifetime to hours or days and remove the refresh step.
- Token revocation — add a step where the API checks a revocation list instead of just verifying the token signature (slower but enables instant logout).
- Scope-based access — include the scopes in the token response and show the API checking them: e.g., 'GET /profile requires scope:profile'.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
actor Client
participant API Server
participant Auth Service
Client->>Auth Service: POST /token (credentials)
Auth Service->>Auth Service: Validate credentials
Auth Service-->>Client: Bearer token + expiry
Client->>API Server: GET /resource (Authorization: Bearer token)
API Server->>Auth Service: Verify token
Auth Service-->>API Server: Token valid ✓
API Server-->>Client: Resource data
Note over Client,Auth Service: Token expires
Client->>Auth Service: POST /token/refresh
Auth Service-->>Client: New bearer token
Frequently asked questions
- What is a bearer token and how does it differ from OAuth?
- A bearer token is any opaque string in an Authorization header that grants API access — the server checks its signature or looks it up in a cache to verify it's real. OAuth is a delegation protocol (e.g., 'let this app access my Google photos without knowing my password'); bearer tokens are the token type OAuth uses, but also used in simpler schemes like API keys. This diagram shows the token flow for a service-to-service API or a single-tenant app.
- Should I issue short-lived access tokens and refresh tokens like in the diagram?
- Yes, if the token could be compromised (e.g., it lives in a mobile app or browser). Short-lived access tokens (5–15 min) limit the window if one leaks; refresh tokens (days/weeks) let you reissue access without re-authenticating. If tokens only live on secure servers, a longer access token (hours) is fine. The diagram shows the safer pattern.
- What happens if a token expires mid-request?
- The API returns 401 Unauthorized. The client catches this, exchanges the refresh token for a new access token, retries the request, and the second attempt succeeds. Add a retry loop in the diagram if you want to show this — Client retries after the Auth Service issues a new token.
- How do I adapt this for API keys, mTLS, or JWT validation?
- For API keys, skip the token request — the client already has one and sends it in every request. For mTLS, skip the token entirely and use mutual TLS certificates instead. For JWT validation, the Auth Service signs tokens instead of storing them, and the API Server validates the signature locally (no network call to Auth Service to verify). The structure is the same; implementation details change.