Title: Access & Refresh Tokens with Rotation

Date: 2025-12-23

Status: Accepted

Context: Go pet-project, implementing authentication with tokens.

Decision

1. Use two types of tokens:

   • Access token: short-lived (10 minutes), used for API requests.
   • Refresh token: long-lived (30 days), used to refresh access tokens.

2. Refresh Token Rotation:

   • Each refresh token is single-use.
   • After use, the old refresh token is marked as revoked/used.
   • The server issues a new pair of tokens (Access + Refresh).

3. Login flow:

   • Client sends login + password.
   • A new token pair is issued.
   • Old refresh tokens: remain valid (allow multiple devices)

4. Storage:

   • Refresh tokens are stored hashed in the database.

   • Access tokens are not stored.

   • Minimal fields for refresh token:

     UserID
     TokenHash
     ExpiresAt
     RevokedAt
     

5. Security considerations:

   • Refresh tokens are hashed.
   • Access tokens are short-lived to minimize risk if leaked.
   • Rotation allows detection of stolen refresh tokens.

Sequence diagram

sequenceDiagram
    participant Client
    participant Server

    Note over Client,Server: Login
    Client->>Server: POST /auth/login (credentials)
    Server-->>Client: access_token + refresh_token

    Note over Client,Server: Normal API usage
    Client->>Server: GET /api/tasks (Bearer access_token)
    Server-->>Client: 200 OK

    Note over Client,Server: Token expired
    Client->>Server: GET /api/tasks (expired access_token)
    Server-->>Client: 401 Unauthorized

    Note over Client,Server: Refresh flow
    Client->>Server: POST /auth/refresh (refresh_token)
    activate Server
    Server->>Server: Validate refresh token
    Server->>Server: Revoke old refresh token
    Server->>Server: Issue new token pair
    deactivate Server
    Server-->>Client: access_token + refresh_token

    Note over Client,Server: Continue with new tokens
    Client->>Server: GET /api/tasks (Bearer new access_token)
    Server-->>Client: 200 OK

Consequences

• Safe support for multiple devices / sessions.
• Users do not depend on old tokens.
• Easy to manage logout and token revocation.