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.
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 in the header.
The minor version uses date-based (coordinated universal time, UTC) versioning 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
If you want to use the API version from November 15, 2025, you need to use the 2025-11-15 version. Refer to the API versioning section for more information.
Required headers
You must add these headers to every Admin API request:
-H "Authorization: YOUR_API_KEY_HERE" \
-H "PubNub-Version: 2026-02-09" \
-H "Content-Type: application/json"
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 "PubNub-Version: 2026-02-09" \
-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. |
| 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 |
| Account | Secret key | Read | View secret keys across all keysets |
| Account | Secret key | Read & write | Rotate secret keys across all keysets |
| Account | Usage & Monitoring | Read | View usage and monitoring data for whole account |
| 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 |
| App | Secret key | Read | View secret keys for keysets within the selected app |
| 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 |
| 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
Base URL
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 |
You must add Authorization, PubNub-Version and Content-Type headers to every Admin API request. Refer to the Required headers section for more information.
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-02-09" \
-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 passed as a header (e.g., 2024-11-15) and handle the natural evolution of features within a major version. These changes happen monthly or quarterly and may include:
- new fields or endpoints
- field renames for clarity
- behavior modifications
- new optional features
Date-based versioning provides temporal context. 2024-11-15 means the Admin API as it existed on November 15, 2024. You must include the minor version header in all requests:
PubNub-Version: 2026-02-09
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
- 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: | apiKey |
|---|---|
Header parameter name: | x-session-token |