Automate Multitenancy with the PubNub Admin API

The PubNub Admin API enables a wide range of multitenancy architectures, supporting SaaS platforms, OEM products and white-label solutions.

Because Apps and Keysets can now be created, configured, and governed programmatically, PubNub can serve as the real-time engine behind any multi-customer environment with strong isolation, security, and operational automation.

In this article, you'll learn how to set-up multitenancy models using common patterns and how the Admin API supports each model.

Create a Service Integration

In order to use the Admin API, you'll need to create a Service Integration. Service Integrations are created for a secure connection between the PubNub Admin API and other services using API keys.

Service Integrations are created in the PubNub Admin Portal by an Account Owner or Admin.

1. Once in the Admin Portal, click on the dropdown in the top right corner of the Admin Portal. Click on Organization settings.

2. Click on API Management.

3. Click on Create Integration.

4. Provide a name for the service integration.

5. Set the level of permissions of the integration (account-level, app-level, or keyset-level).

6. Choose the App, PubNub Resource, and Access.

7. Generating the an API Key and copy it down somewhere secure.

Tenant-Per-Customer Model for SaaS Platforms

This is the most widely adopted model for SaaS products requiring strong data separation. Each customer receives an isolated PubNub App containing one or more Keysets used by that customer’s environment.

Typical industries include healthcare, finance, logistics, customer support, and real-time collaboration, where regulatory boundaries or data ownership requirements dictate isolation.

Create an application container per customer:

POST /v2/apps  
{  
  "name": "AcmeCorp-App"  
}

Then, create an isolated keyset:

POST /v2/keysets  
{  
  "keyset": {  
    "name": "AcmeCorp-Prod",  
    "appId": "app_123456",  
    "type": "production"  
  }  
}

You'll then want to configure tenant-specific features, such as Presence, Message Persistence, App Context, etc:

PATCH /v2/keysets/keyset_abc123/config  
{  
  "presence": { "interval": 30 },  
  "messagePersistence": { "enabled": true, "retention": 30 }  
}

Finally, retrieve usage for billing or analytics:

GET /v2/usage-metrics?entityType=keyset&entityId=keyset_abc123&metrics=msgs_total,publish

This model supports strict compliance requirements and clean segmentation of operational workloads. It is the approach used by customers who provision tenants daily or weekly.

White-Label PubNub Deployments

In white-label scenarios, a platform provider offers real-time capabilities for its own customers, who in turn provide services to their users. PubNub operates entirely behind the scenes, while the end customer interacts solely with the provider’s UI or SDK.

This means that the provider creates and manages Apps and Keysets on behalf of their customers, who do not require a PubNub account and allows PubNub features, such as messaging, state synchronization, presence, push, file sharing, and metadata, to be embedded seamlessly into another company’s branded software.

A typical white-label workflow would look something like this:

1. Customer signs up for the white-label platform.

2. Backend system creates a PubNub App for that customer.

3. Keysets are generated for production and testing environments.

4. Configuration is applied based on the customer’s chosen tier.

5. Usage data is retrieved through the Metrics API and surfaced inside the provider’s product.

This model allows the provider to maintain full control over billing, feature availability, and operational governance.

OEM Embedded Real-Time Engine

OEM scenarios involve embedding PubNub directly into a hardware or software product. The product vendor provisions PubNub Apps and Keysets automatically as new devices, deployments, or customers come online.

This model is well suited to vendors who want to embed real-time infrastructure without building or maintaining it themselves, while preserving isolation between customer deployments.

Use cases include IoT platforms, telemedicine devices, AR/VR applications, virtual environments, and broadcast or streaming tools.

Here is a typical provisioning flow for OEM embedded real-time engines:

POST /v2/apps                # Create OEM-managed app  
POST /v2/keysets             # Create keyset(s) for devices or instances  
PATCH /v2/keysets/.../config # Apply OEM-defined configuration  
GET /v2/usage-metrics        # Retrieve usage data per deployment

Multi-Environment Tenant Provisioning (Dev / Test / Stage / Prod)

The Admin API allows the creation of separate environments for each tenant, using the type parameter for Keysets:

"type": "testing" | "production"

This enables each customer to receive dedicated development, staging, and production instances, each with its own configuration, rate limits, and usage reporting.

Feature-Tiering for Product Plans

The Admin API allows dynamic configuration of service tiers by selectively enabling or tuning Keyset features:

Feature	API Section	Availability
Presence	presence	Available now
Message Persistence	messagePersistence	Available now
Stream Controller	streamController	Available now
App Context	appContext	Available now
File Sharing	files	Available now
APNs / FCM Push	apns, fcm	Available soon

Example: enabling features for a premium tier:

PATCH /v2/keysets/config  
{  
  "presence": {"interval": 30},  
  "messagePersistence": {"enabled": true, "retention": 30},  
  "appContext": {"enabled": true}  
}

This makes it possible for SaaS providers to map subscription plans directly to platform capabilities.

Usage-Based Billing at the Tenant or Sub-Tenant Level

The Usage Metrics API supports detailed measurement for each App or Keyset, including:

1. Total messages

2. Publish/Subscribe counts

3. Storage consumption

4. Presence activity

5. Push notifications

6. MTD (month-to-date) metrics

GET /v2/usage-metrics?entityType=keyset&entityId=keyset_abc123&metrics=publish,subscribe_msgs

This allows SaaS providers and OEM vendors to implement:

1. Per-customer billing

2. Usage dashboards

3. Consumption-based cost controls

4. Internal chargeback reporting

Scoped Authorization Models for Multitenant Backends

Service Integrations allow API keys to be scoped at the account, App, or Keyset level.

Typical patterns include:

1. Central backend with account-level permissions

2. Tenant-specific microservices using app-level scopes

3. Client-side services restricted to individual keysets

This ensures strong isolation and follows least-privilege principles.

In Summary

The PubNub Admin API supports the full lifecycle of multitenant real-time applications, including:

1. Automated tenant creation

2. Environment provisioning

3. Operational configuration

4. Usage analytics for billing and monitoring

5. Role-scoped security models

6. Embedding PubNub into OEM and white-label offerings

These patterns allow organizations to adopt PubNub not only as a messaging backend, but as a foundational component of their multitenant platform architecture.

What's Next: Upcoming OEM and Partner Capabilities

In an upcoming release, PubNub will introduce a set of OEM and Partner-focused capabilities designed for platforms that manage real-time functionality on behalf of their own customers.

These enhancements will allow each end-customer to be represented as a first-class entity within the partner’s PubNub account, with the ability to associate and manage multiple Keysets per End-Customer and apply configuration or policy updates programmatically. Partners will also be able to maintain and administer these end-customer assignments directly through an expanded Partner Portal, enabling more structured delegation and operational control across large customer bases.

The Usage Metrics API will additionally support usage retrieval at the end-customer level, allowing partners to implement precise billing models, monitor consumption patterns, and build customer-facing analytics and dashboards. These capabilities are designed for OEM, white-label, embedded, and re-seller scenarios where PubNub’s real-time infrastructure is delivered as part of a broader multi-customer solution.

These features are currently available for early access through PubNub’s OEM/Partner program. Organizations interested in enabling End-Customer entities, multi-keyset management, or End-Customer usage reporting can contact PubNub sales for availability, onboarding, and program details.