Multi-Tenant and Subaccounts

How tenant isolation works in the API. Subaccount programmatic provisioning lands with Agency OS.

The Multi-Tenant Model

Every request to the senderZ API is scoped to a single tenant. A tenant represents one customer account — your organization, your data, your phone lines. Tenant isolation is not a feature you enable; it is the foundational layer of the platform. Every database query, every message, every compliance record is bound to a tenant_id.

When you sign up and receive an API key, that key is permanently associated with your tenant. Every API call you make — sending messages, managing contacts, creating templates, registering webhooks — operates exclusively within your tenant boundary. You cannot read, write, or even detect another tenant’s data.

How Isolation Works

From your perspective as an API consumer, tenant isolation is invisible. Your API key determines which tenant context you operate in. You never pass a tenant_id in your requests — the platform resolves it automatically from your authentication credentials.

Behind the scenes, the API enforces isolation through a guard called assertTenantOwnership(). This function runs on every request that touches tenant-scoped data. It verifies that the resource you are accessing (a message, a contact, a template) belongs to the same tenant as your API key. If the tenant IDs do not match, the request is rejected before any data is returned.

This enforcement is not optional and cannot be bypassed. It applies to every route in the API — including admin-provisioned resources. The guard operates at the data access layer, which means even if a bug existed in a higher-level route handler, the ownership check would still block cross-tenant access.

What Is Tenant-Scoped

The following resources are fully isolated per tenant. No tenant can access another tenant’s data in any of these categories:

Resource	Description
Messages	Every sent and received message, including delivery status and channel used
Contacts	Your contact book — names, phone numbers, groups, and group memberships
Templates	Message templates with variable syntax, categorized by type (OTP, alert, marketing)
Campaigns	Bulk send campaigns, recipient lists, and campaign status
Webhooks	Registered webhook URLs, secrets, event subscriptions, and delivery logs
API keys	All API credentials generated under your account
Opt-outs	STOP keyword records — which phone numbers have opted out of your messages
Consent logs	TCPA consent audit trail — timestamps and consent types for every number
Usage records	Monthly usage tracking, API call counts, and billing events
AI personas	Auto-reply AI configuration and training sources

Phone lines (dedicated Apple devices) can be shared across tenants through a pooled assignment model or dedicated exclusively to a single tenant. The phone assignment mode is configured by the platform operator — not by tenants themselves.

Your API Key Is Your Tenant

There is no separate tenant selection step in the API. Your key is your identity:

# This request sends a message within YOUR tenant — automatically
curl -X POST https://api.senderz.com/v1/messages \
  -H "Authorization: Bearer tf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "channel": "auto",
    "body": "Hello from my tenant"
  }'

If you generate multiple API keys under the same account, they all operate within the same tenant. Keys can have different rate limits and permissions, but they share the same tenant boundary.

Subaccounts Today

If you are an agency or a platform that needs to manage multiple tenants — for example, sending messages on behalf of several clients — senderZ supports this through manually provisioned subaccounts.

Contact our sales team and we will:

Create a separate tenant for each of your clients
Link those tenants under your agency account
Give your team delegated access to manage each tenant
Assign phone lines (pooled or dedicated) per client tenant

Each client tenant is fully isolated from every other tenant, including your own agency tenant. Your clients’ data never intermixes.

Subaccounts Tomorrow: Agency OS

Programmatic subaccount management is on the roadmap as part of Agency OS, targeted for Q3 2026 general availability. When Agency OS ships, you will be able to:

Create tenants via API — provision a new client tenant with a single POST request
Manage API keys per tenant — generate, rotate, and revoke keys for each subaccount
Assign phone lines programmatically — allocate pooled or dedicated numbers to client tenants
View aggregated analytics — see message volume, delivery rates, and usage across all your subaccounts in one dashboard
Set per-tenant limits — control message volume and new contact caps per client

Until Agency OS launches, all subaccount provisioning is handled by our team. The manual process typically takes less than 24 hours from request to active tenant.