gridpilot.gg/docs/architecture/api/AUTH_FLOW.md

Authentication and Authorization Flow (API)

This document defines how authentication and authorization are enforced in the API.

Shared contract:

• docs/architecture/shared/AUTH_CONTRACT.md

1) Enforcement location (strict)

All enforcement happens in the API.

The API must:

• authenticate the actor from the session
• authorize the actor for the requested capability
• deny requests deterministically with appropriate HTTP status

2) Canonical request flow

HTTP Request
  ↓
Authentication (resolve actor)
  ↓
Authorization (roles, permissions, scope)
  ↓
Controller (transport-only)
  ↓
Core Use Case
  ↓
Presenter mapping
  ↓
HTTP Response

3) Non-negotiable rules

1. Deny by default unless explicitly public.
2. The actor identity is derived from the session.
3. Controllers do not contain business rules.

Related:

• Authorization model: docs/architecture/api/AUTHORIZATION.md
• Guards definition: docs/architecture/api/GUARDS.md