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

POST#

Retrieve an access token for an end customer

Path

/oem/access-token

GET#

List customers

Path

/oem/customers

POST#

Create a customer

Path

/oem/customers

GET#

List app IDs for a customer

Path

/oem/customers/{customerId}/applications

POST#

Assign keysets to a customer

Path

/oem/customers/{customerId}/keysets

GET#

List keyset IDs assigned to a customer

Path

/oem/keysets

POST#

Generate a keyset

Path

/keys

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 \
2  -H 'content-type: application/json' \
3  -H 'x-session-token: <portal-session-token>' \
4  -d '{
5    "permissions": [
6      "business-object:read",
7      "business-object:write",
8      "business-object:update:activation",
9      "business-object:write:config",
10      "business-object:update:map",
11      "dashboard:read",
12      "dashboard:write",
13      "decision:read",
14      "decision:read:config",
15      "decision:read:rule",
16      "decision:write",
17      "decision:update:activation",
18      "decision:write:config",
19      "decision:update:rule",
20      "metric:read",
21      "metric:write"
22    ],
23    "expiresIn": "24h",
24    "externalId": "0123CUSTOMER",
25    "customerUserId": "user@example.com",
26    "accountId": 123456,
27    "appId": 12345678
28  }'

show all 28 lines

Parameters

* required

externalId* required#

type: Type: string

The unique customer ID you assigned when creating the customer record

customerUserId* required#

type: Type: string

Email address or unique identifier for the customer's user. Email is recommended for visibility and audit.

accountId* required#

type: Type: number

Your PubNub account ID

appId* required#

type: 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* required#

type: Type: string[]

List of permission strings. See Permissions reference.

expiresIn#

type: 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

accountId#

type: Type: number

Your PubNub account ID

Location

Query

Response

1{
2  "result": [
3    {
4      "id": "8b8f0888-88d8-888f-b8be-cd8e88888888",
5      "externalId": "0123CUSTOMER",
6      "name": "ABC Customer",
7      "created": "2025-05-14T23:09:06.942Z",
8      "updated": "2025-05-14T23:09:06.942Z",
9      "appCount": 1,
10      "keysetCount": 2
11    },
12    {
13      "id": "cd8f88ab-8c8c-888f-a8f8-888caeb88888",
14      "externalId": "0124CUSTOMER",
15      "name": "XYZ Customer",
16      "created": "2025-05-14T23:12:46.542Z",
17      "updated": "2025-05-14T23:12:46.542Z",
18      "appCount": 2,
19      "keysetCount": 2
20    }
21  ]
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" \
2  -H "Content-Type: application/json" \
3  -H "x-session-token: <portal-session-token>" \
4  -d '{
5    "externalId": "<customer-unique-id>",
6    "name": "<customer-name>",
7    "accountId": <your-PubNub-account-id>
8  }'

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

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

Parameters

* required

externalId* required#

type: Type: string

Your unique identifier for this customer. A customer's external ID cannot be changed after you save the customer record.

name* required#

type: Type: string

Display name for the customer

accountId* required#

type: Type: number

Your PubNub account ID

keysetIds#

type: Type: number[]

Keyset IDs to assign to the customer at creation time

Response

1{
2  "result": {
3    "id": "888abea-ffd8-88b8-888c-8cf8888888a8",
4    "externalId": "0122CUSTOMER",
5    "name": "Sample Customer",
6    "created": "2025-06-04T16:53:33.885Z",
7    "updated": "2025-06-04T16:53:33.885Z",
8    "keysets": []
9  }
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

customerId#

type: Type: string

The PubNub-generated customer ID. See List customers.

Location

Path

accountId#

type: Type: number

Your PubNub account ID

Location

Query

Response

1{
2  "result": [
3    {
4      "id": 12345678,
5      "accountId": 123456
6    },
7    {
8      "id": 98765432,
9      "accountId": 123456
10    }
11  ]
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" \
2  -H "Content-Type: application/json" \
3  -H "x-session-token: <portal-session-token>" \
4  -d '{
5    "keysetIds": [<keysetId1>, <keysetId2>],
6    "accountId": <your-PubNub-account-id>
7  }'

Parameters

customerId#

type: Type: string

The PubNub-generated customer ID. See List customers.

Location

Path

keysetIds#

type: Type: number[]

Array of keyset IDs to assign

Location

Body

accountId#

type: Type: number

Your PubNub account ID

Location

Body

Response

1{
2  "result": {
3    "id": "888abea-ffd8-88b8-888c-8cf8888888a8",
4    "externalId": "0122CUSTOMER",
5    "name": "Sample Customer",
6    "created": "2025-06-04T16:53:33.885Z",
7    "updated": "2025-06-04T16:53:33.885Z",
8    "keysets": [
9      {
10        "id": 1234567,
11        "assignedAt": "2025-06-04T18:54:41.311Z"
12      }
13    ]
14  }
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

accountId#

type: Type: number

Your PubNub account ID

Location

Query

customerId#

type: Type: string

The PubNub-generated customer ID. See List customers.

Location

Query

Response

1{
2  "result": [
3    {
4      "id": 1272361,
5      "assignedAt": "2025-06-04T18:54:41.311Z"
6    }
7  ]
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 '{
5  "app_id" : <app_id>,
6  "type": 1|0,
7  "properties" : {
8      "name" : <key_name>,
9      "history" : 1|0,
10      "message_storage_ttl" : 1...365,
11      "lms" : 1|0,
12      "max_message_size" : 1800 ... 7200,
13      "multiplexing" : 1|0,
14      "apns" : 1|0,
15      "uls" : 1|0,
16      "objects" : 1|0,
17      "objects_region" : <region_name>,
18      "objects_user_events_enabled": 1|0,
19      "objects_space_events_enabled" : 1|0,
20      "objects_membership_events_enabled" : 1|0,
21      "pam_objects_disallow_getallchannels" : 1|0,
22      "pam_objects_disallow_getalluuids" : 1|0,
23      "files_enabled" : 1|0,
24      "files_s3_bucket_region" : <region_name>,
25      "files_ttl_in_days" : 0...,
26      "presence" : 1|0,
27      "presence_announce_max" : 1...100,
28      "presence_interval" : 1...300,
29      "presence_deltas" : 1|0,
30      "presence_leave_on_disconnect" : 1|0,
31      "presence_stream_filtering" : 1|0,
32      "presence_active_notice_channel" : <channel_name>,
33      "presence_debounce" : 1|0,
34      "presence_store_event_messages" : 1|0,
35      "wildcardsubscribe": 1|0,
36      "objects_ref_integrity" : 1|0
37  }
38}'

show all 38 lines

Parameters

app_id#

type: Type: number

The PubNub app ID to create the keyset under

type#

type: Type: number

Keyset type: 1 for production, 0 for testing

properties.name#

type: 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{
2  "result": [
3    {
4      "id": 1272361,
5      "assignedAt": "2025-06-04T18:54:41.311Z"
6    }
7  ]
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.