Skip to main content

​
Operator console

The operator console is the oversight surface for staff at a launching bank. An operator can inspect operations, mandates, and audit events, and can suspend a mandate. An operator cannot create payments, transfers, mandates, or cards — no such endpoint exists under /v1/ops/*. The operator role is view and suspend only by design.

​
Operator identity

Operators authenticate through a separate Auth0 client from customers (NEOBANK_AUTH0_OPS_CLIENT_ID), and a successful operator login must carry the operator role in its identity token. The API rejects an operator login that lacks the role, and rejects an operator identity presented through the customer application:
apps/api/src/neobank/api.py
Operator login requires multifactor authentication. The /v1/session/login endpoint sets the MFA authentication-context-class reference whenever operator=true is passed. The callback merges the ID token’s amr claim with the namespaced step_up_methods claim the post-login Action sets to ["passkey"] for passkey-primary logins — Auth0 records passkeys as performed_amr: ["phr"] in tenant logs only, never in the token’s amr — and rejects a step-up or operator transaction whose combined methods miss the accepted set (mfa, webauthn, passkey, phr):
apps/api/src/neobank/api.py
See Authentication for the full BFF and step-up flow.

​
Operator endpoints

Every route under /v1/ops/* is gated by require_role("operator"). The available endpoints are: The two documentation endpoints are operator-gated and include_in_schema=False, so they do not appear in the public Swagger at /docs. They exist so an operator can inspect the live contract and try endpoints against their own session without leaving the authenticated context. There is deliberately no operator endpoint to create a payment, transfer, mandate, or card; to execute a mandate; or to resume a mandate. Suspension immediately moves the mandate to revocation_pending, cancels unsent reservations, and queues the upstream grant revoke. It cannot return to active. Confirmed read evidence moves it to revoked; a definitive failure moves it to revocation_failed, while uncertain submission remains disabled for operator review. See Agent mandates for the full state flow.

​
Authenticated API docs in production

Production disables the unauthenticated documentation routes, but registers guarded equivalents at /docs and /openapi.json. Any authenticated principal — customer session, operator session, or agent bearer token — can load them; signed-out requests receive 401. The page fetches the caller’s CSRF token from GET /v1/session and attaches X-CSRF-Token to unsafe try-it-out requests, so POST calls run against the caller’s own session. Both routes stay include_in_schema=False and never appear in the exported contract. In development the standard unauthenticated FastAPI docs serve the same paths.

​
Web entry point

The web app exposes the console at /ops. An operator who signs in is redirected there and kept off the customer surface:
apps/web/src/components/app-shell.tsx
The operator sidebar shows only the Operations entry; the customer navigation (Send, Mandates, Cards) is hidden. A customer identity cannot reach /ops — the role check runs in both the API and the shell.

​
What an operator does here

  • Triage a stuck operation. Open /v1/ops/operations, find the operation by recency, and read its state, failure_code, and submission_uncertain flag. Cross-reference the request_id against Audit to see who initiated it.
  • Stop a runaway mandate. POST /v1/ops/mandates/{id}/suspend moves the mandate to revocation_pending, which blocks further mandate executions by every client and rule before the worker attempts upstream revocation.
  • Investigate attribution. /v1/ops/audit filtered by customer_id shows every sensitive action with its full actor chain, including which authorized client executed a mandated payment.
POST /v1/ops/mandates/{id}/suspend writes an audit event attributed to the operator. Suspension is not reversible. There is no /v1/ops/mandates/{id}/unsuspend or customer-facing resume endpoint.
  • Audit — the audit trail operators read alongside this console.
  • Authentication — Auth0 clients, MFA, and the step-up flow.
  • Agent mandates — who can execute a mandate, and what suspension stops.