Token Based Authentication: Mermaid Flowchart Diagram

Token Based Authentication flowchart diagram

About Source

Token-based authentication is a stateless authentication mechanism where the server issues a signed token to an authenticated client, and the client presents that token on every subsequent request — eliminating the need for a server-side session store.

The dominant token format is JWT (JSON Web Token), which encodes a JSON payload (claims like user ID, roles, expiry) and a cryptographic signature in a compact base64-encoded string. The server signs the token with either a symmetric secret (HS256) or an asymmetric key pair (RS256, ES256). Any service with the corresponding key can verify the signature without querying a central session store — this is the key scalability advantage.

The authentication flow starts with login: the client sends credentials, the server validates them, generates a signed JWT with a short expiry (typically 15 minutes to 1 hour for access tokens), and returns it. The client stores the access token — in memory for SPAs (safest, lost on page reload), or in localStorage/sessionStorage (accessible to JS, XSS risk). The client includes the token in the Authorization: Bearer header on every API request.

A refresh token (long-lived, opaque, stored server-side) is issued alongside the access token. When the access token expires, the client presents the refresh token to a /refresh endpoint to obtain a new access token without re-authenticating. Refresh tokens should be rotated on each use and invalidated on logout.

The server validates each request by verifying the JWT signature, checking the exp claim, and optionally checking a token blocklist for revoked tokens. Unlike sessions, JWTs cannot be invalidated server-side without a blocklist — this is the primary tradeoff. See Secure Session Storage for the session-based alternative, and JWT Authentication Flow for JWT-specific details.

Frequently asked questions

Token-based authentication is a stateless mechanism where the server issues a signed token (typically a JWT) to an authenticated client. The client sends the token in the `Authorization: Bearer` header on every subsequent request. The server verifies the token's signature without querying a session store, making it horizontally scalable.

When the short-lived access token expires, the client sends its refresh token to a `/refresh` endpoint. The server validates the refresh token, issues a new access token (and optionally a new refresh token), and invalidates the old refresh token. Rotating refresh tokens on each use means a stolen refresh token can only be used once before detection.

Session-based authentication stores user state in a server-side session store (typically Redis) and gives the client only an opaque session ID cookie. Token-based authentication encodes state in the token itself and requires no server-side store for validation. Sessions can be instantly invalidated by deleting the server record; JWTs cannot be revoked before expiry without a blocklist.

Storing access tokens in memory (a JavaScript variable) is safest — they are lost on page reload but are inaccessible to other scripts and XSS payloads. Storing in `localStorage` persists across reloads but is readable by any JavaScript on the page, creating XSS risk. HttpOnly cookies are the most secure storage for refresh tokens, protecting them from script access.

mermaid

flowchart TD
    A[User submits credentials\nusername and password] --> B[Server validates credentials\nagainst user database]
    B --> C{Valid credentials?}
    C -- No --> D[Return 401 Unauthorized]
    C -- Yes --> E[Generate signed JWT access token\nexp: 15 min, includes user ID and roles]
    E --> F[Generate opaque refresh token\nexp: 7 days, stored in DB]
    F --> G[Return access token + refresh token\nto client]

    G --> H[Client stores access token\nin memory or localStorage]
    H --> I[Client makes API request\nAuthorization: Bearer access-token]
    I --> J[Server verifies JWT signature]
    J --> K{Token valid\nand not expired?}
    K -- No, expired --> L[Client sends refresh token\nto /auth/refresh endpoint]
    L --> M{Refresh token valid\nand not revoked?}
    M -- Yes --> N[Issue new access token\nRotate refresh token]
    N --> I
    M -- No --> O[Force re-login]
    K -- Yes --> P[Extract claims\nuser ID and roles from JWT]
    P --> Q[Authorize request\nbased on role claims]
    Q --> R[Return protected response]