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, for example:

• Create and configure keysets
• Query usage metrics for the whole account or grouped by keyset or application

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 Service Integrations.
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 on one of three levels: account, application, keyset.

Permissions granted at a higher level propagate down the hierarchy. For example, if you grant permission at the application level, it is also granted for all of its keysets. Key principles are:

• Least privilege: Grant only the minimum permissions required for the intended use case
• Scope-based: Permissions are tied to specific resources and operations
• Account-level: All Service Integrations are scoped to your account

Permission grant example​

Assume you have two apps and three keysets in the following structure:

• App 1: Keyset A, Keyset B
• App 2: Keyset C

When Service Integration is granted the usage:read permission on the account level, it can read usage for the whole account, so both apps (App 1, App 2) and all three keysets (A, B, C).

When Service Integration is granted the usage:read permission on the App 1 level, it can read usage for App 1 and both keysets (A, B).

When Service Integration is granted the usage:read permission on a specific keyset, it can only read usage for this keyset.

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:

• Use environment variables or secure secret management systems and 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