> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neobank.proofof.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate customer and operator browser sessions, scoped agents, and local debug callers.

# Authenticate each route class

Every request resolves to one principal. Customer and operator browsers use server-side Auth0 sessions; agents use Auth0 access tokens; local development can enable explicit debug headers.

## Resolve principals in order

The API evaluates these credential types:

1. Local debug headers when `NEOBANK_DEBUG_AUTH_ENABLED=true` in development or test
2. Agent OAuth bearer tokens
3. Customer or operator session cookies

Production rejects debug authentication. Caddy removes caller-supplied debug identity headers, but preserves `Authorization` so OAuth-authenticated agents and server integrations can reach the API. Customer browser routes still require the customer session, origin check, and cross-site request forgery token.

## Protect browser sessions

FastAPI completes the Auth0 Authorization Code flow with Proof Key for Code Exchange and stores an opaque session in Redis. Secure deployments use an HTTP-only `__Host-neobank_session` cookie.

Unsafe cookie-authenticated methods require both the exact `Origin` and the session’s `X-CSRF-Token`. Sensitive transfers, mandate changes, and card actions also consume a short-lived confirmation intent bound to the normalized payload.

Customer routes reject agents and operators. Operator routes use a separate Auth0 application and remain limited to view and suspend behavior.

## Bind agent execution to a mandate

Agent tokens must contain the configured audience, issuer, scope, subject, and client identifier. A transfer also requires an active mandate owned by the same customer and authorizing that client or internal rule.

The service rechecks the mandate state, provider binding, expiry, beneficiary, caller, rule, count, total cap, and rolling limits before reserving an execution. The worker then verifies the exact upstream grant before payment.

## Use debug authentication locally

Debug headers can exercise customer, operator, and agent routes without Auth0. They remain restricted to development and test. Local live mode also requires loopback application origins, PostgreSQL, Redis, Vault, and the exact reviewed HTTPS Perflo origins.