Multi-Tenancy & Sub-Accounts

This section is for software integrators and platform partners who serve their own customers on top of SendSeven — agencies, SaaS products, and resellers who want to create a workspace per end-customer and drive everything from code, without ever logging into each workspace by hand.

By the end of this section you'll be able to:

• Provision a sub-account (a new workspace) for each of your customers — Creating Sub-Accounts
• Control any sub-account from a single parent token using the X-Tenant-ID header — no per-workspace login — Cross-Account API Access
• Register webhooks and API resources into a sub-account programmatically — Cross-Account API Access
• Send your customer a link to connect their own channel (WhatsApp, Telegram, email, …) — Channel Connect Links

The model: Billing Account → Tenants

SendSeven's multi-tenancy has two levels:

Billing Account  (your organization — one payment relationship)
 ├── Tenant A    (a workspace / "sub-account")
 ├── Tenant B    (another workspace)
 └── Tenant C    ...

Concept	What it is	In the API
Billing Account	The top-level entity that owns the payment method and groups workspaces. Has owners and members.	Set when you sign up; owners can add more tenants to it.
Tenant	A single isolated workspace — its own conversations, contacts, channels, campaigns, users, webhooks, and API tokens. This is what we call a sub-account.	tenant_id on every resource; the unit of data isolation.

There is no separate "reseller" object

A "sub-account" is simply another Tenant under your Billing Account. There is no distinct reseller/agency entity to create — you create tenants, and they are grouped by the billing account they belong to. Everything in this section builds on that.

Isolation is per-tenant

Every row of customer data (conversations, contacts, channels, messages, campaigns) is scoped to exactly one tenant_id, and the API enforces that boundary on every request. A credential resolves to exactly one tenant per request — the only way to cross that boundary is the explicit, billing-account-scoped tenants:manage grant, which still can never reach a tenant in a different billing account.

What you can automate today

Here is an honest capability matrix. Everything marked ✅ is fully supported via the public API.

Capability	Supported?	How
Create additional sub-accounts (tenants) under your billing account	✅	POST /tenants (billing-account owner only)
Create a scoped API token for a specific tenant	✅	POST /api-tokens
Control sub-accounts from one parent token (no per-workspace login)	✅	tenants:manage grant + X-Tenant-ID header
Register webhooks into a sub-account from a parent token	✅	POST /webhook-endpoints + X-Tenant-ID
Generate a channel connect link for a customer to self-connect	✅	POST /channel-connect-tokens
Listen for channel lifecycle across sub-accounts	✅	channel.* webhook events
Cross the boundary into a different billing account	❌	Not possible by design — hard isolation boundary

Choosing your integration shape

There are two common patterns. Pick based on who owns the channels.

Pattern A — Channels live in your workspace(s)

You operate the channels (your WhatsApp numbers, your email domains) and use SendSeven as the engine behind your own product. You may use a single tenant, or one tenant per customer for data separation. You issue channel connect links so customers attach their channel into the workspace you designate.

Pattern B — A workspace per customer, controlled centrally

You provision one sub-account per end-customer (Creating Sub-Accounts), then drive each one from a single parent token via X-Tenant-ID. Each customer's data stays fully isolated in its own tenant, but you never have to log in or juggle one credential per workspace. This is the pattern most agencies and multi-customer SaaS products want.

Next steps

• Creating Sub-Accounts — provision a workspace per customer
• Cross-Account API Access — one token, many sub-accounts, via X-Tenant-ID
• Channel Connect Links — let customers connect their own channels