PubNub Admin API

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:

1. Log in to Admin Portal as Owner or Account Admin.
2. Navigate to Organization Settings → API Management.
3. Create a new Service Integration with an initial API Key.
4. 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: 2025-11-15" \
-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: 2025-11-15" \
  -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:

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:

Available permissions​

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:

Provision apps and keysets (no usage)​

Read-only access​

Narrowly scoped to one app​

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

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:

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: 2025-11-15" \
  -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: 2025-11-15

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