# ADR-0003: Define Authentication Contracts

Status: Accepted  
Date: 2026-04-29

## Context

Authentication requires distinct access and refresh behavior, stable duration parsing, and safe development defaults.

## Decision

- Use `AuthHandler` for public authentication routes and `AccountHandler` for authenticated account routes.
- Add a JWT `type` claim that distinguishes access and refresh tokens.
- Verify token type at the boundary that consumes the token.
- Store configuration durations as `time.Duration` values.
- Replace known development JWT placeholders with a random runtime secret during configuration loading.

## Consequences

- Access tokens authenticate protected requests.
- Refresh tokens rotate token pairs through database sessions.
- Invalid duration values fail during startup.
- Tokens signed with the generated development secret expire when the process restarts.
- Multi-instance deployments require a stable configured secret.