Roles & Access Model
====================

Access Principles
-----------------

- **Multi-tenant isolation.** Every request carries an authenticated tenant
  context; services enforce tenant scoping on all data access.
- **Least privilege.** Distinct credential types per surface (dashboard JWT,
  API key, super-admin token, payment-link auth) with separate middleware
  chains; API keys can be scoped, deactivated, and revoked with full audit
  logs.
- **Environment gating.** Sandbox access is default; live (production) access
  is explicitly granted per tenant through the Identity service's production
  access gate.
- **Dual control.** High-value operations (OTC orders, transfers) require a
  second authorized approver.

Platform Roles
--------------

.. list-table::
   :header-rows: 1
   :widths: 22 78

   * - Role
     - Responsibilities & access
   * - Tenant owner
     - Full dashboard access for their business: manages team members, API
       keys, IP whitelists, webhook configuration, passcodes, and all product
       features. Can switch between businesses they belong to.
   * - Tenant team member
     - Dashboard access scoped by assigned role; roles are assigned, updated,
       and deactivated/reactivated by tenant administrators. Role claims are
       embedded in session JWTs and enforced per-RPC.
   * - API integration (machine)
     - Programmatic access via API keys (live/sandbox prefixed). Subject to
       per-tenant rate limits, idempotency requirements, and optional IP
       whitelisting.
   * - Approver
     - A team member authorized to approve or reject pending OTC orders and
       transfers under the dual-authorization workflow; approval decisions
       are recorded separately from order creation.
   * - Gravv operations (super admin)
     - Internal staff access via super-admin tokens (separate live and
       sandbox tokens) and the admin console: cross-tenant queries,
       statistics, account/virtual-account administration, payee verification
       resets, and operational resets. All admin operations flow through
       dedicated, separately-authenticated RPCs.
   * - End customer
     - No direct platform access. Customers of tenants interact through
       tenant channels or public hosted payment pages (payment links), which
       expose only the minimal public surface with their own rate limiting.
   * - Service identity (machine)
     - Internal service-to-service calls authenticated via propagated
       metadata and interceptors; CI deployments authenticate to GCP via
       OIDC workload identity federation, not stored credentials.

Credential Lifecycle
--------------------

- API keys: create, list, activate, deactivate, revoke — with per-key audit
  logs retrievable by the tenant.
- Team members: invite, role update, status update, removal, reactivation.
- Passcodes: add, authenticate, remove, recover (step-up factor).
- Secrets: rotated centrally in GCP Secret Manager per environment; services
  load secrets at startup with environment-based namespacing.