> ## 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.

# The subaccount organization model

> How parent organizations, subaccounts, and resources compose in Orbit — the scope chain behind API keys, per-resource attribution, cross-subaccount visibility, and where subaccount isolation stops short of tenant isolation.

# The subaccount organization model

Orbit has two levels of grouping that are easy to conflate: the **tenant**, which is the hard data boundary, and the **organization tree** inside a tenant, which is the soft, business boundary resellers use to model their own customers. This page defines that tree — parent organization, subaccounts, and the resources each one owns — so you can decide, per customer, whether to open a subaccount or a separate tenant, and so you can predict who sees what once the tree exists.

For the mechanics of creating and operating subaccounts, see [White-label subaccounts](/guides/subaccounts-reseller) and [Subaccounts API](/api-reference/subaccounts). For the hard boundary underneath, see [Tenant isolation](/concepts/tenant-isolation). This page is the model those guides operate on.

## Section 1 — Parent org, subaccount, resource: the hierarchy

A **subaccount** is a full organization — a row in the shared `public.organizations` catalog with its own id, plan, API keys, users, and branding — created with a **parent** pointer to the reseller's organization. Organizations with no parent are parent orgs; organizations with one are subaccounts. Nesting stops there: a subaccount cannot parent another subaccount.

```text theme={null}
Parent organization (the reseller)
 ├── Subaccount: Acme Retail      plan: growth    API keys, users, wallet
 ├── Subaccount: Delta Logistics  plan: business  API keys, users, wallet
 └── Subaccount: West Clinic      plan: starter   API keys, users, wallet
```

Two properties make the tree meaningful:

* **The API key resolves one organization.** Every key is issued against exactly one org — parent or subaccount. The auth layer resolves the key to that org on every request and derives the tenant from the org's `tenant_id`; nothing in the request can override it. A caller is strictly one node of the tree at a time.
* **The subaccount is a scope inside a tenant, not a tenant.** The entire parent family — the parent org and all its subaccounts — resolves to **one** tenant schema. Sibling subaccounts share `tenant_<tenant_id>`; only owners *outside* the family get a different schema. What separates siblings inside that shared schema is org ownership: every row carries an owning-org column and every read or write is gated against it (worked example in [Tenant isolation, Section 3](/concepts/tenant-isolation)).

So the scope chain on any request is: **API key → organization → tenant schema → row-level ownership gate.** The key picks the org, the org picks the schema, ownership picks the rows.

## Section 2 — Connection modes: which connection a subaccount's channel resolves to

Per channel (SMS, Voice, Email, WhatsApp, and the LLM/voice-AI providers), a parent decides which connection its subaccounts' traffic runs on. Three modes exist, and they compose per channel:

| Mode                 | How a subaccount's traffic resolves                                                                                                                                                                                                                  | Billing shape                                                           |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Platform default** | Orbit's shared connection. Nothing to configure; the out-of-the-box mode for every subaccount.                                                                                                                                                       | Standard usage rates on the subaccount's own pricing.                   |
| **Full-access**      | The subaccount's normal scoped operation — its own API keys, senders, and wallet on the platform's connections, fully operated by whoever holds its key. This is the default mode every subaccount is in unless the parent opts the family into BYO. | Standard usage metering with per-subaccount attribution (Section 3).    |
| **Reseller (BYO)**   | The parent's own connection for that channel — its SIP trunk, SMPP account, sending domain, WABA, or LLM key — inherited by **every** subaccount. No per-subaccount override; inheritance is all-or-nothing per channel.                             | A flat per-transaction platform fee replaces the platform default rate. |

The mechanics — the one-active-connection-per-type registry, masked credentials, the `403` when a subaccount tries to manage provider config, and fail-safe fallback — live in [Per-channel connection mode: BYO vs platform default](/guides/subaccount-connection-modes). One rule from that guide belongs in the model: **BYO is parent-scoped and family-wide.** A subaccount reading the reseller slice gets an empty provider list and a "managed by your parent" view; the parent is the single point of configuration.

## Section 3 — Per-resource attribution: the reason a reseller can bill per subaccount

Every billable resource a subaccount creates is attributed to **that subaccount's organization id** from the moment it exists. Attribution is not a report computed after the fact — it is the ownership column on each row, and usage aggregates roll up along it.

| Resource                   | Attribution                                                                                                                                                        | What the parent can do with it                                               |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| **Messages and calls**     | Each send, inbound message, and call carries the org it was made by.                                                                                               | Per-subaccount usage reads and CSV export for invoicing.                     |
| **Numbers**                | A purchased number is owned by one org; reassignment between siblings is an explicit mutation ([Number lifecycle → Reassign to a Subaccount](/numbers/lifecycle)). | Move a number to another sibling — ownership travel with the gate enforced.  |
| **Wallet**                 | Each org holds its own wallet. The parent funds subaccounts with credit transfers and caps them with `monthly_spend_cap_cents`.                                    | Fund, cap, and read the stated reseller margin per subaccount.               |
| **Contacts and campaigns** | Audiences and campaign artifacts live in the shared tenant schema but are owned by the org that created them.                                                      | Sibling-campaign isolation; see Section 5.                                   |
| **API keys**               | A key is minted against one org and scopes every request to it.                                                                                                    | Never hand a parent key to an end-customer — issue the subaccount's own key. |

That attribution is what makes the reseller statement vendible: usage rolls up per day × per meter **per subaccount** at wholesale cost, the parent's margin markup applies over it, and an invoice to the end-customer is an export away. The concept beneath pricing — how a send resolves a rate — is on [Pricing & rate resolution](/concepts/pricing-rate-resolution).

## Section 4 — Cross-subaccount visibility: who can see what

Visibility follows the ownership gate, with one asymmetry: **the parent sees the tree; a subaccount sees only itself.**

* **The parent org** reads and writes across its family: list all subaccounts, read each one's usage, transfer credits, set pricing, manage branding, reassign owned numbers, and operate any subaccount directly. The parent's vantage is the whole tree in Section 1.
* **A subaccount sees its own org only.** Its key resolves to itself; a request for a sibling's resource hits the ownership gate and fails. It reads the parent's provider configuration as an empty list and its overview surfaces show a "managed by your parent" state where the parent owns the decision.
* **A subaccount's own admin** is admin of that one org — the `{id}` in a subaccount-management path is accepted only when it is the caller's own organization. An end-customer with a subaccount key can never climb the tree upward or sideways.

The practical consequence: cross-sibling consolidation (a tree-wide usage rollup, a numbers move, a pricing sweep) is always a parent operation. If your end-customers need a consolidated view of each other, they are not subaccounts of one parent — they are separate tenants or separate orgs under their own parents.

## Section 5 — Structuring audiences: campaigns, contacts, and shared assets

Two attributes split here — **ownership is per-org; some assets can still be shared downward.**

* **Contacts are subaccount-scoped.** Audience data an end-customer uploads or syncs belongs to their subaccount and is gated to it. A subaccount builds its campaign audiences from its own contacts; a sibling's list is unreachable.
* **Campaigns are per-subaccount artifacts.** A campaign is created, targeted, and reported within one org. Dedicated senders on a campaign belong to the org that owns the campaign.
* **Shared assets flow downward, not sideways.** Rate cards are the model example: the parent authors a pricing card once in its library and assigns it to any subaccount — the child resolves rates against the assigned card as a pointer, never a copy. Provider connections (Section 2) inherit the same way. Branding offers both shapes: inherit the parent's branding wholesale, or override per subaccount.

The rule to remember: **shared assets are authored at the parent, referenced by the child; audience and send artifacts are authored at the child, invisible to siblings.** Design downstream tooling — bi-directional sync jobs, billing exports, support tooling — against that shape and you never have to special-case subaccounts.

## Section 6 — What the subaccount model is NOT

Three comparisons settle most "should this be a subaccount?" debates:

* **Not tenant isolation.** Subaccounts share one tenant schema; the isolation between siblings is the org-ownership gate the application enforces, not a database boundary. The SOC 2-visible guarantee Orbit makes — one schema per tenant, server-side tenant resolution — applies **across** families, never **within** one. The full argument is on [Tenant isolation](/concepts/tenant-isolation).
* **Not an RBAC role.** Admin-of-subaccount is not a permission a user's role grants; it is a property of **which organization the credential resolves to**. Roles inside an org (admin, member) still exist and still govern what a user of that org can do — but no role widens a caller beyond their own org.
* **Not a tenant shortcut.** A subaccount is one API call cheaper than a new tenant, but it is also *inside* the parent's tenant: same schema, family-wide BYO inheritance, parent-visible usage. Choose a separate tenant when the customer needs a hard data boundary from the reseller; choose a subaccount when the relationship is genuinely reseller-to-end-customer and consolidated operation is the point.

## Cross-references

* [White-label subaccounts](/guides/subaccounts-reseller) — provision, fund, brand, and retire the nodes of this tree.
* [Per-channel connection mode: BYO vs platform default](/guides/subaccount-connection-modes) — the mode table from Section 2 in mechanics form.
* [Tenant isolation](/concepts/tenant-isolation) — the hard boundary underneath, and the Section 3 worked example this page extends.
* [Subaccounts API](/api-reference/subaccounts) — the endpoint catalog for the tree.
* [Pricing & rate resolution](/concepts/pricing-rate-resolution) — where per-subaccount attribution meets a rated usage event.
* [Rate cards](/billing/rate-cards) — the model case for parent-authored, child-referenced shared assets.