> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Operator plane vs tenant plane — admin APIs and their audit model

> The two-plane split between everything your API key can reach (tenant plane) and the platform's operator surfaces (operator plane): what the operator plane ships, how operator authentication is separated from your tenant credentials, what gets audited, and how you verify a platform-side change.

# 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](/concepts/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](/concepts/authentication-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](/guides/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](/compliance/compliance-health) 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](/guides/subaccounts-reseller) treats
as the unit of audit.

## See also

* [Authentication and session model](/concepts/authentication-model) — the three customer credential classes the operator chain is separate from
* [Tenant isolation](/concepts/tenant-isolation) — the tenant plane's data boundary
* [Audit log](/guides/audit-log) — your organization's verification surface
* [Subaccounts and the reseller model](/guides/subaccounts-reseller) — audit boundaries across subaccounts
* [Operator observability map](/concepts/operator-observability-map) — the tenant-side observability surfaces for your own traffic
* [Compliance health](/compliance/compliance-health) — the tenant-owned posture view