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

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.