Skip to main content

​
Operator plane vs tenant plane

Orbit runs two planes. The tenant plane is everything your organization’s API keys and dashboard sessions can reach — your messages, contacts, numbers, flows, billing wallet, and audit log. The operator plane is the platform team’s own surface: the admin API (/api/v1/admin/*) and the internal operations dashboards that ride on it, none of which your credentials can touch. This page defines the split, catalogues what the operator plane ships, explains why it runs on a separate authentication chain, and — the part that matters to you — shows how every operator action that touches your organization is recorded where you can read it.

​
Section 1 — The two-plane naming

The split exists so one credential system never has to answer two different questions. Tenant plane. Every route your dv_ API keys and dashboard session tokens authorize. Requests resolve to exactly one organization from the credential itself, and the data you reach lives in your tenant schema — the isolation model in Tenant isolation is the tenant plane’s boundary. Your audit log under Settings → Audit log is a tenant-plane surface: it records what happens inside your organization. Operator plane. The platform-level admin API that the internal operations console calls. Operator requests are not tenant-scoped — an operator reads across organizations (tenant rosters, billing timelines, audit search) and acts on platform-wide state (the IP denylist, provider health, rate decks). The operator plane exists to run the platform: billing operations, tenant lifecycle, compliance tooling, and incident response. One sentence to hold: your API key never authorizes an operator route, and an operator session never acquires your tenant identity silently — the two planes cross only through recorded, auditable actions.

​
Section 2 — What the operator plane ships

The operator plane is a first-class route family. The surfaces below are the ones whose actions are attributable and audited; they are grouped by what they operate on. Tenant and billing operations
  • Billing timeline (GET /api/v1/admin/tenants/:id/billing-timeline) — the unified per-tenant financial history operators reconcile against: credit grants, deductions, top-ups, renewals, and plan changes in one ordered feed.
  • Plan of record (/api/v1/admin/tenants/:id/plan-of-record/*) — a snapshot of each organization’s effective plan and feature state, with point-in-time diffs, so an operator can answer “what plan was this tenant on last Tuesday” instead of inferring it from current state.
  • Tenant bulk export (POST /api/v1/admin/tenants/bulk-export) — an asynchronous, job-tracked export of tenant detail for support and migration workstreams, with secrets redacted from the payload.
  • Crypto refund initiation (POST /api/v1/admin/billing/crypto-refund) — the operator-side refund path for cryptocurrency top-ups, gated behind a dedicated rate limit because it moves money.
Numbers and compliance
  • Numbers compliance status (GET /api/v1/admin/numbers/compliance-status) — a per-row verification and registration posture read across the number pool, used to spot an org whose numbers drifted out of compliance posture.
  • PII-masked reports — the operator reporting surface projects revenue, call logs, and attribution rows through a masking layer so operator dashboards and exports never carry raw end-user identifiers where a masked value is sufficient.
Security and audit
  • Audit search (GET /api/v1/admin/audit-logs) — cross-tenant search over the audit ledger with actor, action, resource, severity, IP, and date-range filters. This is the operator’s cockpit view of the same ledger class you read per-organization.
  • IP denylist (/api/v1/admin/audit-security/ip-denylist) — the platform-wide inbound IP denylist; entries are created with the acting operator’s identity and an optional expiry, and every change is written to the audit chain. A create that would denylist the operator’s own address is flagged in the response rather than silently locking the operator out.

​
Section 3 — The authorization split

Authentication and session model defines three customer credential classes — API keys, dashboard session tokens, and the SCIM provisioning token. The operator plane adds a fourth, separate chain for exactly one audience: platform operators. Operators sign in with a password-less, single-use email code, and only addresses on the platform operator allowlist can complete the exchange. A successful sign-in mints a bounded operator session (a signed token carried in an httpOnly cookie) that the admin API accepts. Three properties matter:
  • No tenant credential reaches an operator route. Your dv_live_sk_ key, your dashboard JWT, and your SCIM token are all rejected on the admin surface; the operator session is rejected on yours. There is no credential that spans both planes.
  • Super-admin checks are per-route, not inherited. Authentication admits an operator; every sensitive route then re-checks operator authorization on its own, so a route added without the check fails closed to 403, not open.
  • Masking is applied per surface. Operator reads that span organizations (reports, exports) project through the PII-masking layer, and operator sessions are short-lived by construction — a new sign-in supersedes the operator’s prior sessions.
The one place the planes touch by design is support access: an operator impersonation session into your organization requires an owner-granted, time-boxed support-access window on your side, and the grant refuses when the window is denied, unset, or expired. Grant, deny, and session-listing controls are the tenant-owned gates under /api/v1/settings/security/support-access — Section 5 covers the controls you hold on that surface.

​
Section 4 — The audit model

Operator actions that touch an organization write to the same append-only audit ledger your Audit log page reads. The record keeps four fields you can act on: the actor (the operator’s identity, not an anonymous “platform” actor), the action (a human-readable phrase with the machine event code preserved), the resource (your organization, number, plan, or billing record), and the timestamp with the source IP where a request was involved. Details payloads are scrubbed of operator-side internals before they reach what you can read. The practical consequence: a platform-side change to your organization is verifiable by you, after the fact, in your own surface. If an operator adjusts your plan, suspends or reinstates a tenant, grants trial credit, or touches your numbers’ posture, a corresponding entry appears in your organization’s audit ledger — filter Settings → Audit log by the actor or action, or pull the same rows from GET /api/v1/settings/audit-logs or via the audit.log.created webhook into your SIEM. The operator’s cross-tenant audit search (Section 2) is a different view of the same ledger class — it does not create a second, hidden record. What is not in your audit log: operator actions on platform-wide state that never touch a tenant (the IP denylist, provider routing, rate decks) and pure read traffic. Anything that changed your organization is attributed and visible.

​
Section 5 — What tenants get back

The operator plane is read-only for you by construction, but three tenant-owned surfaces expose the operator-side truth you have a stake in:
  • Your audit ledger (Settings → Audit log, or GET /api/v1/settings/audit-logs) — the verification surface above: every attributable operator action on your organization, filterable and exportable, with a full-history export path for evidence pulls.
  • Support access control (/api/v1/settings/security/support-access) — the consent gate for operator impersonation. You grant or deny the window, list your active operator sessions, and end them early; an operator cannot mint a session into your organization without an active grant.
  • Compliance and attestation posture — the tenant-side pages under Compliance and the number-pool posture reads expose the same per-tenant compliance status the operator plane monitors, scoped to your organization, so the posture an operator sees is one you can read yourself rather than take on trust.
Resellers should note the boundary holds per organization: operator actions on a subaccount are recorded in that organization’s ledger, which Subaccounts and the reseller model treats as the unit of audit.

​
See also