API operations for partners

The partner API lets PubNub partners manage customers, assign keysets, generate access tokens, and control what end customers can do in the embedded Illuminate UI.

Partial endpoint list

This page covers the API operations needed for the Illuminate embedding workflow. It is not the complete list of partner API endpoints. Contact PubNub Support or your account representative for the full list.

For a guided walkthrough of how to use these endpoints together, see Embed the Illuminate UI in your portal.

Authentication

All endpoints on this page use x-session-token authentication. Generate a token from your Admin Portal credentials:

1curl --location --request POST 'https://admin.pubnub.com/api/me' \
2--header 'Content-Type: application/json' \
3--data-raw '{
4  "email": "'$LOGIN'",
5  "password": "'$PASSWORD'"
6}'

Pass the token as x-session-token (or X-Session-Token) in every subsequent request. Tokens are session-scoped.

Base URL: https://admin.pubnub.com/api

Endpoint index

Method	Path	Description
POST	`/oem/access-token`	Retrieve an access token for an end customer
GET	`/oem/customers`	List customers
POST	`/oem/customers`	Create a customer
GET	`/oem/customers/{customerId}/applications`	List app IDs for a customer
POST	`/oem/customers/{customerId}/keysets`	Assign keysets to a customer
GET	`/oem/keysets`	List keyset IDs assigned to a customer
POST	`/keys`	Generate a keyset

Retrieve an access token

Generates a short-lived token that authenticates end customers and carries their permissions in the embedded UI. Call this on each customer login.

Endpoint: POST https://admin.pubnub.com/api/oem/access-token

Request

1curl https://admin.pubnub.com/api/oem/access-token \
-H 'content-type: application/json' \
-H 'x-session-token: <portal-session-token>' \
-d '{
  "permissions": [
    "business-object:read",
    "business-object:write",
    "business-object:update:activation",
    "business-object:write:config",
    "business-object:update:map",
    "dashboard:read",
    "dashboard:write",
    "decision:read",
    "decision:read:config",
    "decision:read:rule",
    "decision:write",
    "decision:update:activation",
    "decision:write:config",
    "decision:update:rule",
    "metric:read",
    "metric:write"
  ],
  "expiresIn": "24h",
  "externalId": "0123CUSTOMER",
  "customerUserId": "user@example.com",
  "accountId": 123456,
  "appId": 12345678
}'
show all 28 lines

Parameters

* required

Parameter	Description
`externalId` * Type: string	The unique customer ID you assigned when creating the customer record
`customerUserId` * Type: string	Email address or unique identifier for the customer's user. Email is recommended for visibility and audit.
`accountId` * Type: number	Your PubNub account ID
`appId` * Type: number	The app ID assigned to this customer. See List app IDs for a customer. PubNub verifies that keysets under this app belong to the customer.
`permissions` * Type: string[]	List of permission strings. See Permissions reference.
`expiresIn` Type: string	A partner access token defaults to a 1-hour lifetime and can be set up to a maximum of 24 hours.

Response

1{
2  "accessToken": "222a22bc-333d-40ef-gh55-6ij777k08888"
3}

Use accessToken as the token parameter in the iframe URL. See Embed the Illuminate UI in your portal.

List customers

Returns the list of customers you have added in PubNub, including their PubNub-generated IDs.

Endpoint: GET https://admin.pubnub.com/api/oem/customers

Request

1curl -X GET "https://admin.pubnub.com/api/oem/customers?accountId=<your-PubNub-account-id>" \
2  -H "x-session-token: <portal-session-token>"

Parameters

Parameter	Location	Description
`accountId` Type: number	Query	Your PubNub account ID

Response

1{
"result": [
  {
    "id": "8b8f0888-88d8-888f-b8be-cd8e88888888",
    "externalId": "0123CUSTOMER",
    "name": "ABC Customer",
    "created": "2025-05-14T23:09:06.942Z",
    "updated": "2025-05-14T23:09:06.942Z",
    "appCount": 1,
    "keysetCount": 2
  },
  {
    "id": "cd8f88ab-8c8c-888f-a8f8-888caeb88888",
    "externalId": "0124CUSTOMER",
    "name": "XYZ Customer",
    "created": "2025-05-14T23:12:46.542Z",
    "updated": "2025-05-14T23:12:46.542Z",
    "appCount": 2,
    "keysetCount": 2
  }
]
22}
show all 22 lines

The id field is the PubNub-generated customer ID. Use it in path parameters for other endpoints.

Create a customer

Creates a customer record in PubNub. Provide only the account ID if you are not yet ready to assign keysets.

Endpoint: POST https://admin.pubnub.com/api/oem/customers

Request

1curl -X POST "https://admin.pubnub.com/api/oem/customers" \
-H "Content-Type: application/json" \
-H "x-session-token: <portal-session-token>" \
-d '{
  "externalId": "<customer-unique-id>",
  "name": "<customer-name>",
  "accountId": <your-PubNub-account-id>
}'

To assign keysets at creation time, include the optional keysetIds field:

1"keysetIds": [<keysetId1>, <keysetId2>]

Parameters

* required

Parameter	Description
`externalId` * Type: string	Your unique identifier for this customer. A customer's external ID cannot be changed after you save the customer record.
`name` * Type: string	Display name for the customer
`accountId` * Type: number	Your PubNub account ID
`keysetIds` Type: number[]	Keyset IDs to assign to the customer at creation time

Response

1{
"result": {
  "id": "888abea-ffd8-88b8-888c-8cf8888888a8",
  "externalId": "0122CUSTOMER",
  "name": "Sample Customer",
  "created": "2025-06-04T16:53:33.885Z",
  "updated": "2025-06-04T16:53:33.885Z",
  "keysets": []
}
10}

Error responses

Creating a customer that already exists returns 400 Bad Request with the message partner customer unique constraint violated. For example:

1{
2  "message": "partner customer unique constraint violated",
3  "_tag": "BadRequest"
4}

List app IDs for a customer

Returns the app IDs assigned to a customer. You need the app ID to generate an access token. Tokens are issued at the app level, so if a customer has multiple app IDs, choose the one that holds their keysets.

Endpoint: GET https://admin.pubnub.com/api/oem/customers/{customerId}/applications

Request

1curl -X GET "https://admin.pubnub.com/api/oem/customers/<PubNub-customer-id>/applications?accountId=<your-PubNub-account-id>" \
2  -H "x-session-token: <portal-session-token>"

Parameters

Parameter	Location	Description
`customerId` Type: string	Path	The PubNub-generated customer ID. See List customers.
`accountId` Type: number	Query	Your PubNub account ID

Response

1{
"result": [
  {
    "id": 12345678,
    "accountId": 123456
  },
  {
    "id": 98765432,
    "accountId": 123456
  }
]
12}

Assign keysets to a customer

Assigns one or more keysets to a customer. A keyset can only be assigned to one customer. A PubNub partner customer can have up to five keysets assigned to it.

Endpoint: POST https://admin.pubnub.com/api/oem/customers/{customerId}/keysets

Request

1curl -X POST "https://admin.pubnub.com/api/oem/customers/<PubNub-customer-id>/keysets" \
-H "Content-Type: application/json" \
-H "x-session-token: <portal-session-token>" \
-d '{
  "keysetIds": [<keysetId1>, <keysetId2>],
  "accountId": <your-PubNub-account-id>
}'

Parameters

Parameter	Location	Description
`customerId` Type: string	Path	The PubNub-generated customer ID. See List customers.
`keysetIds` Type: number[]	Body	Array of keyset IDs to assign
`accountId` Type: number	Body	Your PubNub account ID

Response

1{
"result": {
  "id": "888abea-ffd8-88b8-888c-8cf8888888a8",
  "externalId": "0122CUSTOMER",
  "name": "Sample Customer",
  "created": "2025-06-04T16:53:33.885Z",
  "updated": "2025-06-04T16:53:33.885Z",
  "keysets": [
    {
      "id": 1234567,
      "assignedAt": "2025-06-04T18:54:41.311Z"
    }
  ]
}
15}

Error responses

Assigning a keyset that's already assigned to another customer returns 500 Internal Server Error. For example:

1{
2  "_tag": "InternalError"
3}

List keyset IDs

Returns the keyset IDs assigned to a customer.

Endpoint: GET https://admin.pubnub.com/api/oem/keysets

Request

1curl -X GET "https://admin.pubnub.com/api/oem/keysets?accountId=<your-PubNub-account-id>&customerId=<PubNub-customer-id>" \
2  -H "x-session-token: <portal-session-token>"

Parameters

Parameter	Location	Description
`accountId` Type: number	Query	Your PubNub account ID
`customerId` Type: string	Query	The PubNub-generated customer ID. See List customers.

Response

1{
"result": [
  {
    "id": 1272361,
    "assignedAt": "2025-06-04T18:54:41.311Z"
  }
]
8}

Generate a keyset

Creates a new keyset that you can then assign to a customer.

Endpoint: POST https://admin.pubnub.com/api/keys

Request

1curl --request POST 'https://admin.pubnub.com/api/keys' \
2--header 'X-Session-Token: <session_token>' \
3--header 'Content-Type: application/json' \
4--data-raw '{
"app_id" : <app_id>,
"type": 1|0,
"properties" : {
    "name" : <key_name>,
    "history" : 1|0,
    "message_storage_ttl" : 1...365,
    "lms" : 1|0,
    "max_message_size" : 1800 ... 7200,
    "multiplexing" : 1|0,
    "apns" : 1|0,
    "uls" : 1|0,
    "objects" : 1|0,
    "objects_region" : <region_name>,
    "objects_user_events_enabled": 1|0,
    "objects_space_events_enabled" : 1|0,
    "objects_membership_events_enabled" : 1|0,
    "pam_objects_disallow_getallchannels" : 1|0,
    "pam_objects_disallow_getalluuids" : 1|0,
    "files_enabled" : 1|0,
    "files_s3_bucket_region" : <region_name>,
    "files_ttl_in_days" : 0...,
    "presence" : 1|0,
    "presence_announce_max" : 1...100,
    "presence_interval" : 1...300,
    "presence_deltas" : 1|0,
    "presence_leave_on_disconnect" : 1|0,
    "presence_stream_filtering" : 1|0,
    "presence_active_notice_channel" : <channel_name>,
    "presence_debounce" : 1|0,
    "presence_store_event_messages" : 1|0,
    "wildcardsubscribe": 1|0,
    "objects_ref_integrity" : 1|0
}
38}'
show all 38 lines

Parameters

Parameter	Description
`app_id` Type: number	The PubNub app ID to create the keyset under
`type` Type: number	Keyset type: `1` for production, `0` for testing
`properties.name` Type: string	Name of the keyset

All other properties fields correspond to PubNub feature flags (enable with 1, disable with 0). The files_s3_bucket_region field controls the storage region for Files. Changing it after initial setup risks losing existing files.

Response

1{
"result": [
  {
    "id": 1272361,
    "assignedAt": "2025-06-04T18:54:41.311Z"
  }
]
8}

Permissions reference

Permissions control what a customer can do in the embedded Illuminate UI. Pass a permissions array when calling Retrieve an access token.

Full read/write access to all of Illuminate: include business-object:write, metric:write, dashboard:write, and decision:write.
Read-only access to all of Illuminate: include business-object:read, metric:read, dashboard:read, and decision:read.

Dependent permissions

Some permissions require decision:update:activation to function correctly. Deactivating a Business Object or editing a metric tied to an active Decision triggers a Decision deactivation. Grant decision:update:activation alongside any permission that may trigger this.

Resource	Permission	Description
Business Object	`business-object:write`	Read and write access to the Business Object, including data fields, JSON mapping, and activation. Includes `business-object:read`, `business-object:update:activation`, `business-object:write:config`, and `business-object:update:map`. Also requires `decision:update:activation` to deactivate linked Decisions.
	`business-object:read`	Read-only access to the Business Object, including its metrics.
	`business-object:update:activation`	Activate and deactivate a Business Object. Also requires `decision:update:activation`.
	`business-object:write:config`	Read and write access to the Business Object, excluding JSON mapping and activation.
	`business-object:update:map`	Add and edit JSON mapping for data fields.
Metric	`metric:read`	Read access to metrics on the Business Object.
	`metric:write`	Read and write access to metrics. Requires `decision:update:activation` to edit a metric tied to an active Decision.
Dashboard	`dashboard:read`	Read-only access to the Dashboard, including action history.
	`dashboard:write`	Read and write access to the Dashboard, including adding and deleting charts.
Decision	`decision:write`	Read and write access to the Decision. Includes `decision:read`, `decision:write:config`, `decision:read:config`, `decision:update:rule`, `decision:read:rule`, and `decision:update:activation`.
	`decision:read`	Read-only access to the Decision.
	`decision:write:config`	Read and write access to Decision configuration, including conditions and actions.
	`decision:read:config`	Read-only access to Decision configuration.
	`decision:update:rule`	Read and write access to Decision rules, including thresholds and execution limits.
	`decision:read:rule`	Read-only access to Decision rules.
	`decision:update:activation`	Schedule, activate, and deactivate Decisions.

Partial endpoint list

Authentication​

Endpoint index​

Retrieve an access token​

Request​

Parameters​

Response​

List customers​

Request​

Parameters​

Response​

Create a customer​

Request​

Parameters​

Response​

Error responses​

List app IDs for a customer​

Request​

Parameters​

Response​

Assign keysets to a customer​

Request​

Parameters​

Response​

Error responses​

List keyset IDs​

Request​

Parameters​

Response​

Generate a keyset​

Request​

Parameters​

Response​

Permissions reference​

Dependent permissions

Authentication

Endpoint index

Retrieve an access token

Request

Parameters

Response

List customers

Request

Parameters

Response

Create a customer

Request

Parameters

Response

Error responses

List app IDs for a customer

Request

Parameters

Response

Assign keysets to a customer

Request

Parameters

Response

Error responses

List keyset IDs

Request

Parameters

Response

Generate a keyset

Request

Parameters

Response

Permissions reference