ADR-002: Authentication Strategy - JWT vs Sessions

Status

Accepted

Context

We needed an authentication mechanism that: - Works across web, mobile, and desktop clients - Is stateless (for horizontal scaling) - Has reasonable token expiration handling

Decision

Hybrid approach: - Access tokens: JWT (short-lived, 15 minutes) - Refresh tokens: Stored in DB with session tracking

Implementation

# Access token (JWT) - in memory only
AccessToken: {
    sub: user_id,
    tenant_id: tenant_id,
    exp: 15 minutes
}

# Refresh token - stored in DB
RefreshToken: {
    user_id: UUID,
    tenant_id: UUID,
    expires_at: 7 days,
    revoked: boolean
}

Consequences

Positive

• Stateless auth enables horizontal scaling
• Short-lived access tokens limit exposure if leaked
• Refresh tokens can be revoked if needed
• Works across all client types

Negative

• Token refresh adds complexity on client
• Must store refresh token securely on client
• Logout requires explicit token revocation

Alternatives Considered

1. Pure session auth: Rejected - doesn't scale horizontally
2. Long-lived JWT without refresh: Rejected - security risk
3. OAuth provider: Considered for future, MVP uses local auth