Gravity SMS Docs

Multi-Tenancy

Gravity SMS is a multi-tenant system. Each tenant operates as an isolated organization with its own RingCentral connection, applications, and message history.

What is a tenant?

A tenant represents a single organization or business unit within the gateway. Each tenant has:

  • A unique identifier in the format tenant_ + 16 hex characters (e.g., tenant_abc123def456abcd).
  • Its own RingCentral account connection and phone numbers.
  • One or more apps, each with its own API key.
  • A status that controls access: active, suspended, or inactive.

Data isolation

Tenant data is strictly isolated. An app-role API key can only access resources belonging to its own tenant:

ResourceScope
MessagesFiltered to the app's tenant. An app can only send from and query messages within its own tenant.
AppsApp-role keys can only view and manage apps within their own tenant.
RingCentral connectionEach tenant has its own independent RingCentral OAuth connection and phone numbers.
WebSocket eventsEvents are scoped to the authenticated connection's tenant and app.

Tenant status

A tenant's status determines whether its apps can make API requests:

StatusEffect
activeFull access. Apps can send and receive messages.
suspendedAPI requests return 403 Tenant suspended or inactive. Messages in the queue will fail.
inactiveSame as suspended. The tenant is fully disabled.
If your API requests return 403 Tenant suspended or inactive, check your subscription status in the dashboard or contact support to restore access.

Roles and tenants

API keys have one of two roles, which interact with the tenant model:

  • API keys are scoped to your account. Each key can only access resources within your own account.

Working with your tenant

Your API key is associated with a specific tenant. The tenantId is included in API responses and WebSocket events so you can correlate data in your system:

  • Message objects include a tenantId field.
  • WebSocket events include tenantId for routing.
  • The messages API accepts tenantId as a query filter.

Related docs