Skip to main content

​
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.