auth-architecture

Store hashed refresh tokens server-side and invalidate each token on use, issuing a new pair. If a previously rotated token is presented again, treat it as theft and revoke all sessions for that user. Use short-lived access tokens (15 minutes) alongside 30-day refresh tokens.

Use HttpOnly session cookies for same-domain web apps since they are CSRF-safe and instantly revocable. Use short-lived JWTs with refresh tokens for SPAs on different domains or mobile apps where stateless verification across services matters.

Use RS256 (asymmetric) so services can verify tokens with only the public key without knowing the signing secret. HS256 requires sharing the secret with every verifying service, increasing exposure if any service is compromised.

Map roles to sets of fine-grained permission strings like "orders:delete", resolve the union of permissions from all user roles, and enforce them with a FastAPI dependency that checks required permissions against token claims. Add resource-level ownership checks in route handlers.

Store refresh tokens in HttpOnly, Secure, SameSite cookies, never in localStorage where JavaScript can access them. HttpOnly prevents XSS-based token theft, and SameSite=lax provides CSRF protection.

Rotate refresh tokens on every use and track recently rotated token hashes. If an already-rotated token is presented again, it indicates replay by an attacker, so revoke all sessions for that user immediately.