Authentication¶

Token Flow¶

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as PostgreSQL

    C->>S: POST /api/v1/auth/login {email, password}
    S->>DB: Verify credentials
    DB-->>S: User record
    S->>DB: Store refresh token
    S-->>C: {access_token, refresh_token}

    Note over C: Access token expires (15m default)

    C->>S: POST /api/v1/auth/refresh {refresh_token}
    S->>DB: Validate & invalidate old refresh token
    S->>DB: Store new refresh token
    S-->>C: {new_access_token, new_refresh_token}

Token Rotation¶

• Access tokens are short-lived (default 15 minutes) and stateless (JWT).
• Refresh tokens are longer-lived (default 7 days) and stored server-side.
• On each refresh, the old refresh token is invalidated and a new pair is issued.
• If a refresh token is reused after rotation, all tokens for that user are revoked (potential theft detected).