--- source_url: https://www.pubnub.com/docs/analytics/decisions/partner-api-operations title: API operations for partners updated_at: 2026-09-30T07:20:08.000Z --- # API operations for partners ## Documentation index To discover more PubNub resources: 1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format. 2. Identify relevant URLs from that index. 3. Fetch the target pages. Do not assume a path exists, always check the index first. 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. :::note 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](https://support.pubnub.com/) 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](https://www.pubnub.com/docs/analytics/decisions/embed-ui-in-partner-sites.md). ## Authentication All endpoints on this page use x-session-token authentication. Generate a token from your Admin Portal credentials: ```bash curl --location --request POST 'https://admin.pubnub.com/api/me' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "'$LOGIN'", "password": "'$PASSWORD'" }' ``` 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 ```bash curl https://admin.pubnub.com/api/oem/access-token \ -H 'content-type: application/json' \ -H 'x-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 }' ``` ### Parameters | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | externalId | string | Yes | | The unique customer ID you assigned when creating the customer record | | customerUserId | string | Yes | | Email address or unique identifier for the customer's user. Email is recommended for visibility and audit. | | accountId | number | Yes | | Your PubNub account ID | | appId | number | Yes | | The app ID assigned to this customer. See [List app IDs for a customer](#list-app-ids-for-a-customer). PubNub verifies that keysets under this app belong to the customer. | | permissions | string[] | Yes | | List of permission strings. See [Permissions reference](#permissions-reference). | | expiresIn | string | Optional | | A partner access token defaults to a 1-hour lifetime and can be set up to a maximum of 24 hours. | ### Response ```json { "accessToken": "222a22bc-333d-40ef-gh55-6ij777k08888" } ``` Use `accessToken` as the `token` parameter in the iframe URL. See [Embed the Illuminate UI in your portal](https://www.pubnub.com/docs/analytics/decisions/embed-ui-in-partner-sites.md). ## 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 ```bash curl -X GET "https://admin.pubnub.com/api/oem/customers?accountId=" \ -H "x-session-token: " ``` ### Parameters | Parameter | Location | Description | | --- | --- | --- | | accountId | number | Optional | | Query | Your PubNub account ID | ### Response ```json { "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 } ] } ``` 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 ```bash curl -X POST "https://admin.pubnub.com/api/oem/customers" \ -H "Content-Type: application/json" \ -H "x-session-token: " \ -d '{ "externalId": "", "name": "", "accountId": }' ``` To assign keysets at creation time, include the optional `keysetIds` field: ```bash "keysetIds": [, ] ``` ### Parameters | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | externalId | string | Yes | | Your unique identifier for this customer. A customer's external ID cannot be changed after you save the customer record. | | name | string | Yes | | Display name for the customer | | accountId | number | Yes | | Your PubNub account ID | | keysetIds | number[] | Optional | | Keyset IDs to assign to the customer at creation time | ### Response ```json { "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": [] } } ``` ### Error responses Creating a customer that already exists returns `400 Bad Request` with the message `partner customer unique constraint violated`. For example: ```json { "message": "partner customer unique constraint violated", "_tag": "BadRequest" } ``` ## 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 ```bash curl -X GET "https://admin.pubnub.com/api/oem/customers//applications?accountId=" \ -H "x-session-token: " ``` ### Parameters | Parameter | Location | Description | | --- | --- | --- | | customerId | string | Optional | | Path | The PubNub-generated customer ID. See [List customers](#list-customers). | | accountId | number | Optional | | Query | Your PubNub account ID | ### Response ```json { "result": [ { "id": 12345678, "accountId": 123456 }, { "id": 98765432, "accountId": 123456 } ] } ``` ## 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 ```bash curl -X POST "https://admin.pubnub.com/api/oem/customers//keysets" \ -H "Content-Type: application/json" \ -H "x-session-token: " \ -d '{ "keysetIds": [, ], "accountId": }' ``` ### Parameters | Parameter | Location | Description | | --- | --- | --- | | customerId | string | Optional | | Path | The PubNub-generated customer ID. See [List customers](#list-customers). | | keysetIds | number[] | Optional | | Body | Array of keyset IDs to assign | | accountId | number | Optional | | Body | Your PubNub account ID | ### Response ```json { "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" } ] } } ``` ### Error responses Assigning a keyset that's already assigned to another customer returns `500 Internal Server Error`. For example: ```json { "_tag": "InternalError" } ``` ## List keyset IDs Returns the keyset IDs assigned to a customer. **Endpoint:** `GET https://admin.pubnub.com/api/oem/keysets` ### Request ```bash curl -X GET "https://admin.pubnub.com/api/oem/keysets?accountId=&customerId=" \ -H "x-session-token: " ``` ### Parameters | Parameter | Location | Description | | --- | --- | --- | | accountId | number | Optional | | Query | Your PubNub account ID | | customerId | string | Optional | | Query | The PubNub-generated customer ID. See [List customers](#list-customers). | ### Response ```json { "result": [ { "id": 1272361, "assignedAt": "2025-06-04T18:54:41.311Z" } ] } ``` ## Generate a keyset Creates a new keyset that you can then assign to a customer. **Endpoint:** `POST https://admin.pubnub.com/api/keys` ### Request ```bash curl --request POST 'https://admin.pubnub.com/api/keys' \ --header 'X-Session-Token: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "app_id" : , "type": 1|0, "properties" : { "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" : , "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" : , "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" : , "presence_debounce" : 1|0, "presence_store_event_messages" : 1|0, "wildcardsubscribe": 1|0, "objects_ref_integrity" : 1|0 } }' ``` ### Parameters | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | app_id | number | Optional | | The PubNub app ID to create the keyset under | | type | number | Optional | | Keyset type: `1` for production, `0` for testing | | properties.name | string | Optional | | 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 ```json { "result": [ { "id": 1272361, "assignedAt": "2025-06-04T18:54:41.311Z" } ] } ``` ## Permissions reference Permissions control what a customer can do in the embedded Illuminate UI. Pass a permissions array when calling [Retrieve an access token](#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`. :::note 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. | Last updated at: 2026-09-30T07:20:08.000Z