Version: 2026-10-14

Introduction

PubNub's Admin API is a REST interface for developers and administrators who need to automate PubNub account management tasks, integrate PubNub configuration into CI/CD pipelines, or build custom provisioning tools.

Admin API allows you to manage your PubNub account configuration via a RESTful API. See Postman collection for the API

Multi-tenancy and SaaS apps

The Admin API helps you build multi-tenant, SaaS, and OEM solutions where you need to provision and manage PubNub resources programmatically for your customers.

Single PubNub instance per customer

When you need a dedicated PubNub instance for each of your customers, use keysets. Each keyset provides:

Isolated publish/subscribe key pairs
Independent configuration for features like Presence, Access Manager, and Message Persistence
Separate usage tracking for billing and cost allocation

This approach works best when each customer needs their own isolated messaging environment with distinct settings.

Multiple PubNub instances per customer

When a single customer needs multiple PubNub instances (for example, separate environments for development, staging, and production, or different product lines), use apps. Apps serve as logical containers that group related keysets together.

A typical multi-tenant structure might look like:

One app per customer, which contains all keysets for that customer
One keyset per environment or product to separate production from testing, or for different use cases

Usage tracking for cost allocation

The Admin API lets you query usage metrics at different granularity levels:

Account level: Total usage across all apps and keysets
App level: Usage for a specific customer or product line
Keyset level: Granular usage for individual environments

Use the Usage endpoints to retrieve metrics and allocate costs to your customers based on their actual consumption.

White-label and partner solutions

If you're building a white-label solution or want to become a PubNub partner with advanced multi-tenant capabilities, contact our sales team to discuss partnership options and custom arrangements.

For more information about the Partner Portal and managing end customers, refer to the Partner Portal documentation.

Prerequisites

To use the Admin API, you must:

Have a valid API key. Only accounts with the Owner or Account Admin roles can create API keys. You can have more than one active API key per account.
Know the Admin API version you want to use.

Get the API key

To get the Admin API key:

Log in to Admin Portal as Owner or Account Admin.
Navigate to Organization Settings → API Management.
Create a new Service Integration with an initial API Key.
Copy the API Key and store it safely. It is shown only once.

Refer to the Authentication and authorization section for more information.

Get the API version

The Admin API uses two-tier versioning: a major version (v2) in the base URL and a date-based minor version.

You have two ways to declare which minor version to use:

Pin in Admin Portal (recommended) — Set your version once in the Portal under Settings → API Version. Every request from your account uses that version automatically. No header needed in your code. This is the preferred approach for long-term integrations because allows you to migrate fully without deployment across all services.
PubNub-Version header — Send PubNub-Version: YYYY-MM-DD in individual requests. Useful for initial exploration, testing a newer version before committing to it, or comparing behavior between versions side by side.

When both are present, the request header takes precedence over the account pin.

Minor versions use date-based (coordinated universal time, UTC) identifiers in the ISO (International Organization for Standardization) 8601 YYYY-MM-DD format, for example:

May 19, 2012 is 2012-05-19
May 29, 2021 is 2021-05-29

Refer to the API versioning section for more information.

Example Admin API request

Get the list of all keysets within an account:

curl -X GET https://admin-api.pubnub.com/v2/keysets \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

If your account does not have a pinned version configured in Admin Portal, include the PubNub-Version header:

curl -X GET https://admin-api.pubnub.com/v2/keysets \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -H "PubNub-Version: 2026-10-14" \
  -H "Content-Type: application/json"

Example response

{
  "keysets": [
    {
      "id": "keyset_abc123",
      "name": "My Production Keyset",
      "applicationId": "app_123456",
      "type": "production",
      "publishKey": "pub-c-1234567890abcdef",
      "subscribeKey": "sub-c-1234567890abcdef",
      "createdAt": "2025-10-27T12:00:00Z",
      "updatedAt": "2025-10-27T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

For more information about Admin API endpoints, refer to the Admin API documentation.

Authentication and authorization

Admin API uses Service Integrations for authentication. A Service Integration is a machine identity that represents a program or service consuming the API. Each Service Integration is scoped to your account and authenticates using API Keys with configurable permissions. All API requests must include the API Key in the Authorization header.

Authentication method

To authenticate to the Admin API, you need to create a Service Integration. This identity exists only within the scope of your account and has specific permissions assigned to it. Service Integrations authenticate using expirable API Keys that must be included in the Authorization header of each request.

When creating a Service Integration, you assign permissions that control what operations it can perform. Always follow the principle of least privilege by granting only the permissions that the client actually needs.

Permissions model

Service Integration permissions control access to specific resources and operations within the Admin API. When you create a Service Integration, you select which permissions to grant based on the operations your application needs to perform. For security reasons, you cannot change permissions of an existing Service Integration once it's created.

Permissions are granted as rows that combine:

a Level (Account / App / Keyset)
a PubNub resource (App / Keyset / Secret key / Usage & Monitoring / OEM Customer)
an Access option (read, write, or read & write, depending on the resource)

Note: Selecting Account as the level doesn't grant full access. You must add a permission row for each resource you want the Service Integration to access. Missing rows for resources result in 403 errors when calling those APIs.

Levels

Levels define the hierarchical scope at which permissions apply:

Level	Scope	Example
Account	All apps and keysets in your account	Read usage metrics for the entire account.
App	A specific app and all its keysets	Manage keysets within a single app.
Keyset	A single keyset	Configure features on one keyset.

Permissions granted at a higher level automatically apply to all resources below it. For example, granting the read permission to Usage on app level also grants it for all keysets in that app.

PubNub resources

PubNub resources define what you can operate on:

Resource	Description	Notes
App	App management	Create, read, and update apps.
Keyset	Keyset management	Create, read, and update keysets.
Secret key	Secret key of a specific keyset	Manage or rotate a specific secret key.
Usage & Monitoring	Usage metrics	Read usage metrics for the entire account, apps, and keysets. Only supports read permissions.
Illuminate	Illuminate management	Create, read, and update all Illuminate resources
Insights	Account insights	List and view which subscribe keys have the most messages, unique channels and users
OEM Customer	Partner Portal management	List, create, and manage Partner Customers.

Available permissions

Level	PubNub resource	Access	Description
Account	App	Read	List and view all apps details
Account	App	Read & write	Create, update, rename, and delete apps
Account	Keyset	Read	List and view keyset details and config
Account	Keyset	Read & write	Create, update, and delete keysets across whole account. Note: Creating a keyset also requires Secret key - Read permission.
Account	Secret key	Read	View secret keys across all keysets, return secret key of newly created keyset
Account	Secret key	Read & write	Rotate secret keys across all keysets
Account	Usage & Monitoring	Read	View usage and monitoring data for whole account
Account	Illuminate	Read	List and view all Illuminate resources and their configurations
Account	Illuminate	Read & write	Create, update, and delete all Illuminate resources
Account	Insights	Read	List and view which subscribe keys have the most messages, unique channels and users
Account	OEM Customer	Read	List and view OEM customer data (partner accounts only)
Account	OEM Customer	Read & write	Create, update, and delete OEM customer data (partner accounts only)
App	App	Read	View details for selected app
App	App	Read & write	Update and delete the selected app
App	Keyset	Read	List and view keyset details within the selected app
App	Keyset	Read & write	Create, update, and delete keysets within the selected app. Note: Creating a keyset also requires Secret key - Read permission.
App	Secret key	Read	View secret keys for keysets within the selected app, return secret key of newly created keyset
App	Secret key	Read & write	Rotate secret keys for keysets within the selected app
App	Usage & Monitoring	Read	View usage and monitoring data for the selected app
Keyset	Keyset	Read	View selected keyset details and configuration
Keyset	Keyset	Read & write	Update and delete the selected keyset and manage its config
Keyset	Secret key	Read	View secret keys for the keyset, return secret key of newly created keyset
Keyset	Secret key	Read & write	Rotate secret keys for the keyset
Keyset	Usage & Monitoring	Read	View usage and monitoring data for the keyset

API key permission examples

Check out the following examples to see how permissions work in practice.

Full access for the entire account

The following permission rows grant full Admin API access for the entire account:

Level	PubNub resource	Access
Account	App	Read & write
Account	Keyset	Read & write
Account	Secret key	Read & write
Account	Usage & Monitoring	Read
Account	OEM Customer	Read & write (for OEM customers only)

Provision apps and keysets (no usage)

Level	PubNub resource	Access
Account	App	Read & write
Account	Keyset	Read & write

Read-only access

Level	PubNub resource	Access
Account	App	Read
Account	Keyset	Read
Account	Usage & Monitoring	Read

Narrowly scoped to one app

The following permission rows grant access to one app and all its keysets:

Level	PubNub resource	Access
App	App ID	Read & write
App	Keyset ID	Read & write

Admin API credentials lifecycle

API Keys have a maximum time to live of 1 year, after which they expire. You can configure shorter expiration periods.

Admin API key rotation

You can issue multiple API Keys per Service Integration for zero-downtime rotation. Create a new key, update your applications, then revoke the old key.

Admin API key revocation

We recommend revoking old API Keys once rotation is complete, even if they haven't expired yet
Revoked keys are immediately invalidated

Security best practices

When working with the Admin API:

Store API keys in a secrets manager or use environment variables—never commit credentials to version control
Use HTTPS only
Rotate credentials regularly, minimum once per year, or more frequently for sensitive operations
Limit credential scope by following the principle of least privilege when assigning permissions
Monitor credential usage in the Admin UI
Revoke unused keys

Requests structure

You should make all Admin API requests to the base URL https://admin-api.pubnub.com/v2.

Example endpoint construction

To access a specific resource, append the resource path to the base URL https://admin-api.pubnub.com/v2/{resource-path}, for example:

https://admin-api.pubnub.com/v2/keysets/12345/config

Request format

The Admin API uses standard HTTP methods to perform operations:

Method	Purpose	Typical Use
`GET`	Retrieve resources	Fetch data, list resources
`POST`	Create resources	Create new entities
`PUT`	Update/replace resources	Full resource updates
`PATCH`	Partially update resources	Partial resource updates
`DELETE`	Remove resources	Delete entities

Required headers

You must add these headers to every Admin API request:

-H "Authorization: YOUR_API_KEY_HERE" \
-H "Content-Type: application/json"

If your account does not have a pinned version set in Admin Portal, also include:

-H "PubNub-Version: 2026-10-14"

Request body format

For requests that include a body (POST, PUT, PATCH), use JSON (JavaScript Object Notation) format:

curl -X POST https://admin-api.pubnub.com/v2/keysets \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -H "PubNub-Version: 2026-10-14" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-keyset",
    "region": "us-east-1"
  }'

API versioning

The Admin API uses a two-tier versioning strategy that combines major versions in the URL with date-based minor versions in headers. This approach provides stability for existing integrations while enabling continuous feature evolution.

Major versions (v1, v2, v3)

The major version appears in the base URL and represents fundamental architectural changes:

https://admin-api.pubnub.com/v2

Admin API is currently on major version 2 (v2).

Major version changes happen every few years and may include breaking changes. When we increment the major version (v2→v3), it signals that the way you interact with the API has changed.

Minor versions (date-based)

Minor versions use date-based identifiers (e.g., 2024-11-15) and provide temporal context. 2024-11-15 means the Admin API as it existed on November 15, 2024. Within those minor versions updates may happen and may include:

removing or renaming an endpoint, field, or enum value
making an optional request field required, or narrowing the values a field accepts
changing the type or meaning of an existing field
changing status codes, error shapes, or the observable behavior of an existing operation

Declaring your API version

You have two ways to tell the API which minor version to use.

Pin in Admin Portal (recommended for long-term integrations)

Navigate to Settings → API Management → Pinned PubNub Admin API version in Admin Portal and select a version. The gateway applies it to every request from your account automatically — no header needed in your code.

Pinning is the preferred approach when you maintain multiple services or teams that all use the API. Migrating to a new version becomes a single change in one place rather than a coordinated deployment across all callers.

PubNub-Version header (useful for testing and migration)

Send the header in individual requests:

PubNub-Version: 2026-10-14

Use the header when:

Exploring the API or setting up a new integration before committing to a version
Testing how a newer version handles your requests without changing the account-wide pin
Running requests for two different versions side by side to compare behavior
Your different integrations require different versions

When the header is present, it overrides the account pin for that request.

Additive changes ship without a new version

We add capabilities to minor versions that are already published. The following changes can appear at any time in the version you already use, and don't get a new date:

new endpoints
new fields in responses
new optional fields in requests
bug fixes

To stay compatible, make sure your integration:

ignores response fields it doesn't recognize instead of failing validation
doesn't depend on an endpoint or a field being absent

API version lifecycle

Minor versions go through a lifecycle based on their date. You don't need to do anything until you start receiving warning headers — at that point you have a year to migrate before enforcement begins.

Lifecycle states

State	When	What happens
Active	Requested date < 1 year old	Normal responses, no lifecycle headers, version supported
Deprecated	Requested date 1–2 years old	Requests succeed with `Deprecation` and `Sunset` headers in the response, support ends. Plan your migration
End-of-life	Requested date ≥ 2 years old	All requests return `410 Gone`

Warning headers

When your requested version enters the deprecated window, every response includes:

Deprecation: Tue, 01 Jul 2026 00:00:00 GMT
Sunset: Wed, 01 Jul 2027 00:00:00 GMT

Header	Meaning
`Deprecation`	The date your requested version became deprecated
`Sunset`	The date your requested version stops working entirely

How to migrate?

If there are no breaking changes to the functionality you use, you can update the pin immediately without any code changes.

If there are breaking changes to the functionality us use, follow this procedure:

Read changelog for breaking changes between your current version and the version you want to move to.
Update your services for any breaking changes.
Test your changes using Pubnub-Version header
Deploy.
Navigate to Settings → API Version in Admin Portal and select the new version.
You can now clear the Pubnub-Version header from your requests.

If there are no breaking changes, you can update the pin immediately without any code changes.

Rate limits & quotas

To ensure service stability and fair usage, the Admin API enforces rate limits on requests. Currently the limit is 120 requests per minute (60 second window). Contact our support if you want to increase the limit.

When you exceed rate limits, the Admin API returns the HTTP 429 Too Many Requests status code.

Rate limit headers

The Admin API includes rate limit information in response headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 46

Header	Description
`X-RateLimit-Limit`	The total number of requests allowed per minute.
`X-RateLimit-Remaining`	The number of requests still available in the current time window.
`X-RateLimit-Reset`	The number of seconds remaining until the rate limit counter resets.

Authentication

API Key: API-Key
HTTP: Bearer Auth
API Key: bearer

API Key issued for Service Integration. To generate one, visit https://admin.pubnub.com/service-integrations

Security Scheme Type:	apiKey
Header parameter name:	Authorization

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	JWT