Skip to main content

​
Org and subaccount model: one vocabulary

Four model pages describe the same hierarchy from different sides: The subaccount organization model defines the tree, Account security model hardens the people in it, Team seat quota counts them, and Roles, teams, and permissions decides what each one can do. A reader deciding “is my customer a subaccount or a separate tenant?” had to synthesize all four. This page is the consolidation: one vocabulary for the whole chain, then explicit hand-offs to the pages that own each layer. Nothing here re-derives a sibling model. Where a layer has an owner page, this page names the hand-off and links it.

​
Section 1 — Org vocabulary, unified

Five nouns carry every request in Orbit. Each has exactly one meaning across the platform:
  • Tenant — the hard data boundary. One tenant owns one database schema (tenant_<id>); nothing crosses that boundary.
  • Organization (org) — a row in the shared organizations catalog: one id, one plan, its own API keys, members, wallet, and branding. Every request resolves to exactly one org.
  • Parent org / subaccount — an org with no parent pointer is a parent org; an org with one is a subaccount. A parent org plus its subaccounts is a family, and the whole family lives inside one tenant. Nesting stops at one level — a subaccount cannot parent another subaccount.
  • Membership — the binding of one person to one org, carrying one role. The same person can hold memberships in several orgs; each membership is scoped to its org and nothing else.
  • Workspace scope — the org a given credential resolves to. A dashboard session scopes to the org you signed into; an API key scopes to the org it was minted against. The workspace scope is fixed per credential and cannot be widened by any role.
When two of these feel interchangeable — “my customer” = subaccount or separate tenant — the deciding question is always the boundary: does that customer need a hard data boundary from you (separate tenant), or is the relationship genuinely reseller-to-end-customer where consolidated operation is the point (subaccount)? Section 6 of The subaccount organization model works through that decision.

​
Section 2 — The subaccount shape: one tenant schema per family

A subaccount is a scope inside a tenant, not a tenant. The entire family — parent org and every subaccount — resolves to one tenant schema; sibling subaccounts share it. What separates siblings inside the shared schema is org ownership: every row carries an owning-org column and every read or write is gated against it. The SOC 2-visible guarantee — one schema per tenant, server-side tenant resolution — applies across families, never within one. The full argument, including the ownership-gate worked example and where subaccount isolation stops short of tenant isolation, is owned by The subaccount organization model and Tenant isolation.

​
Section 3 — Memberships: which layer answers which question

A membership binds a person to one org with one role. Three sibling pages govern three orthogonal properties of that binding — and they must not be conflated:
  • Headcount — owned by Team seat quota. Each org carries a numeric seat quota checked at invite time against live members plus pending invites. It decides only whether one more member may join; a 422 TEAM_MEMBER_CAP_REACHED is this layer refusing. Do not re-derive it here.
  • Capabilities — owned by Roles, teams, and permissions. The role hierarchy and granular permission gates decide what a member may do on every request. No role ever widens a caller beyond their org — the org-ownership gate and the role gate stack; they never compose into a wider one. Do not re-derive it here.
  • Security posture — owned by Account security model. TOTP 2FA, step-up challenges, backup codes, and the org-wide per-role require-2FA policy harden the membership. These are tenant-owned, default-open controls — none are platform mandates. Where that page references “role,” it means the role vocabulary from the roles page, referenced in exactly one place.
So RBAC meets tenancy where the credential resolves: the credential picks the org (tenancy); the role picked by the membership picks what the member can do inside that org (capabilities); the seat quota only ever decided whether the membership could exist (headcount).

​
Section 4 — Workspace scope per key

Every API key is minted against one organization — parent or subaccount — and scopes every request it makes to that org. The auth layer resolves the key to its org on every request and derives the tenant from the org; nothing in the request can override it. A caller with a subaccount’s key is, for the lifetime of that request, that subaccount and nothing else. Two consequences follow:
  • Never hand a parent key to an end-customer. The parent key resolves to the parent org, whose vantage is the whole family tree — usage, wallets, branding, sibling operations. Issue the subaccount’s own key. The mechanics live in White-label subaccounts.
  • A subaccount key can never climb the tree. Its workspace scope is its own org; a request for a sibling’s or parent’s resource hits the ownership gate and fails.
Credential classes themselves — session tokens vs API keys vs the SCIM token — are owned by Authentication and session model; the dv_ key lifecycle is owned by API key lifecycle and rotation.

​
Section 5 — The scope-chain diagram

Every request resolves through the same chain. The key picks the org, the org picks the schema, ownership picks the rows, and the membership’s role gates the capability:
Read the chain top-down on any 403: the workspace scope decided which org you are, the ownership gate decided whose rows you can reach, and the role gate decided what you may do with them. The seat quota never appears on this chain — it ran once, when the membership was invited.

​
Cross-references