Embed Illuminate UI into partner sites

Illuminate can be embedded directly into your application or customer portal, enabling your users to access real-time decisioning, rules management, and analytics within a familiar interface. This integration supports Original Equipment Manufacturer (OEM) and reseller models, where Illuminate functions as a native part of your product offering.

This first section provides the technical steps needed to generate secure access tokens, define appropriate user permissions, and embed the UI with minimal friction. Common scenarios or use cases can be found in the last section.

Prerequisites

Before embedding Illuminate UI, you need to set up your PubNub account for partner integration and establish your customer management structure.

This involves enabling special partner features on your account and creating customer records with associated keysets that will power the embedded UI experience.

Set up your PubNub account

Follow these steps:

Create and set up your account in the PubNub Admin Portal.
Contact PubNub support or your account executive to turn on the Partner feature for your account.

Set up customers and keysets

Adding your customers in PubNub and assigning apps and keysets to each can be accomplished in two ways: through API or the PubNub Partner Portal.

Use Partner Portal

To create a customer through the Partner Portal, sign in to PubNub Admin Portal and go to Partner Portal > Customers.

Provide your customer’s name and a customer ID — this should be your unique identifier for them. Once saved, this ID can’t be changed.
Assign one or more keysets to each customer you created. You can assign one end customer to multiple apps and keysets, but one keyset can only be assigned to one end customer.

Use API

You can create customers, apps, and keysets, and assign up to five keysets to each customer using API. Contact PubNub support or your assigned account representative for more information.

Embed the Illuminate UI

Once your prerequisites are complete, embedding Illuminate involves a secure token-based authentication flow followed by iframe integration.

You'll generate customer-specific access tokens with defined permissions, embed the UI using HTML iframes, and optionally create Illuminate resources for your customers.

Additional API endpoints are provided to help you manage the integration programmatically.

Retrieve the access token

Retrieve a PubNub partner access token for each customer to authenticate API requests and control what they can access in the embedded UI.

When your customer logs into your application, trigger an API call to retrieve the access token.

curl https://admin.pubnub.com/api/oem/access-token \
  -H 'content-type: application/json' \
  -H 'x-session-token: <portal-session-token>' \
  -d '{"permissions": [<list-of-permissions>...], "expiresIn": "24h", "externalId": <customer-unique-id>, "customerUserId": <user-email-address>, "accountId": <account-id>, "appId": <app-id>}'

See the full list of parameters:

Parameter	Description
`x-session-token` Type: `string`	Authentication for your PubNub account. For details, read Generate the x-session token.
`externalId` Type: `string`	Unique identifier you used for your customer when they were added or registered with PubNub
`customerUserId` Type: `string`	The email address or a unique identifier for your customer’s user. The email address is strongly recommended for visibility and audit.
`accountId` Type: `number`	Your PubNub account ID
`appId` Type: `number`	The specific PubNub app under which the keysets assigned to your customers exist. For details, read Get the app ID assigned to your customer.
`permissions` Type: `string`	List of required permissions in an array. For details, read Set required permissions.
`expiresIn` Type: `string`	Optional field that defaults to 1h when it is not provided. Maximum supported value is 24h.

A successful request will return a JSON object containing an accessToken. Use this token in subsequent API calls and for the embedded Illuminate UI to function correctly. In generating the access token, PubNub is validating the keysets under the app ID provided belong to the customer.

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

Sample request to get the access token:

curl 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",
show all 32 lines

Set required permissions

The permissions granted in the token will control which Illuminate features are accessible to your end-customer. Define these based on the functionalities you want your customer to use.

To give a user complete read & write access to all of Illuminate, include business-object:write, metric:write, dashboard:write and decision:write in your access token request.
To give a user read-only access to all of Illuminate, include business-object:read, metric:read, dashboard:read and decision:read in your access token request.

The following table lists more granular permissions than the previous two bullets. For example:

If you want to allow users to edit (read & write) decision rules, but not to edit the decision configuration, then only include decision:update:rule in the access token request.
If you want to allow users to edit the decision rules and view (read) the decision configuration, then include decision:update:rule and decision:read:config.

Illuminate resource	Permission type	Description
Business Object	`business-object:write`	Read and write access to the Business Object, which includes defining data fields, mapping JSON and activating or deactivating the Business Object. Includes these permissions: `business-object:read`, `business-object:update:activation`, `business-object:write:config`, `business-object:update:map`. Users will also need the `decision:update:activation` permission because deactivating a Business Object requires deactivating any Decision tied to the Business Object you’re deactivating.
	`business-object:read`	Read-only access to the Business Object, including the metrics.
	`business-object:update:activation`	Allows users to activate and deactivate a Business Object. Users will need the `decision:update:activation` permission because deactivating a Business Object requires deactivating any Decision tied to the Business Object you’re deactivating.
	`business-object:write:config`	Read and write access to the Business Object, excluding the ability to add and edit the JSON mapping and activate and deactivate the Business Object.
	`business-object:update:map`	Permission to add and edit the JSON mapping for data fields added to the Business Object.
	`metric:read`	Read access to the metric found on the Business Object.
	`metric:write`	Read and write access to the metric found in the Business Object, along with read access to the Business Object data fields and JSON mapping. Users will need the `decision:update:activation` permission because editing a metric requires deactivating the decision the metric is tied to.
Dashboard	`dashboard:read`	Read-only access to the Dashboard, including the 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 these permissions: `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 the Decision configuration page, including adding conditions and setting up actions.
	`decision:read:config`	Read-only access to the Decision configuration page that includes the conditions and actions set up for the Decision.
	`decision:update:rule`	Read and write access to the Decision rules page, including adding and deleting rules, defining thresholds, configuring the action execution limits.
	`decision:read:rule`	Read-only access to the Decision rules page.
	`decision:update:activation`	Allows users to schedule and activate or deactivate Decisions.

Provide all of the permissions listed above in your access token API call if you want your end-customer to be able to read and write all of the Illuminate pages, including Business Object, Dashboards and Decisions. For read-only permissions, only include permissions with read.

Insert UI in your HTML

To embed the Illuminate UI into your portal or web application, insert an iframe with the appropriate token authorization.

<iframe src="https://oem.pubnub.com/embed/<Illuminate-resource>?embed=true&token=<token>" />

See the full list of parameters:

Parameter	Description
`Illuminate-resource`	One of the following: business-objects - where data and metrics are defined dashboards - visualization of metrics and decision actions decisions - where conditions and actions are configured, and decision rules are set up
`token`	Authentication token

Create Illuminate resources for your customers

To create Illuminate resources that your customers see in the embedded Illuminate UI, select which customer you want to create resources for in the Illuminate section of the PubNub Admin Portal. If you’ve built the ability to create Illuminate resources within your site, then resources can be created in your site.

Select customer

Errors

Error responses provide guidance on how to resolve the error. A few common ones are as follows:

A 401 Unauthorized error may be caused by an expired token.
A 403 Forbidden may be because of incorrect account data (like appId, customerId, keysetId) in the request.
A 403 Bad Request may be due to missing or incorrect input information (like incorrect list of permissions, missing required data, malformed JSON).
Contact PubNub Support if you receive a 500 Internal Server Error.
If you or your customers see a There was a problem loading your... message on the Illuminate UI that is iframed into your site, this means the person does not have the permissions to read or write that section or page.

Partner API endpoints

This section provides essential API operations that support your Illuminate embedding workflow, including authentication token generation, customer and keyset management endpoints, and programmatic alternatives to the Partner Portal interface.

This is not the complete list of partner API endpoints. Contact PubNub support or your assigned account representative for the complete list.

Generate the x-session-token

Request a token by calling the following URL: https://admin.pubnub.com/api/me

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

Get the app ID assigned to your customer

This endpoint retrieves the app IDs assigned to a single customer.

You'll need the app ID to retrieve the access token for the embedded Illuminate UI. If a customer has multiple app IDs, select the one you want to generate the access token for, as tokens are issued at the app level.

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

Sample request:

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

Required input data:

Parameter	Description
`accountId`	Your PubNub account ID
`customerId`	The PubNub-generated unique customer ID. For details, read Get the PubNub-generated unique customer ID.

Sample request:

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

Get the PubNub-generated unique customer ID

This endpoint allows you to get the list of customers you’ve added in PubNub, along with other customer-specific information, including the PubNub-generated unique customerIds. You’ll need the customer ID to get the list of apps you’ve assigned to your customer.

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

Sample request:

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

Parameter	Description
`accountId`	Your PubNub account ID

Sample response:

{
   "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",
show all 22 lines

Create a customer in PubNub

This endpoint allows you to create customers in PubNub via API. Provide only the PubNub account ID if you’re not ready to assign keyset IDs to the customer you’re creating.

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

Sample request:

curl -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>
  }'

Parameter	Description
`accountId`	Your PubNub account ID
`externalId`	Unique identifier you used for your customer when they were added or registered with PubNub
`name`	Name of your customer

Optionally, include keyset IDs if you want to immediately assign them:

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

Sample response:

{
   "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": []
   }
}

If you create a customer that is already in PubNub, you’ll receive a 400 Bad Request error.

{
   "message": "partner customer unique constraint violated",
   "_tag": "BadRequest"
}

Assign keysets to customers created in PubNub

This endpoint allows you to assign one or more keyset IDs to customers you’ve created in PubNub. You can assign up to five keyset IDs to a customer.

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

Sample request:

curl -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>, <keysetId1>],
    "accountId": <your-PubNub-account-id>
  }'

Parameter	Description
`accountId`	Your PubNub account ID
`keysetIds`	Array of keyset IDs to assign to the customer

Sample response:

{
   "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"
           }
       ]
   }
}
show all 16 lines

A keyset can only be assigned to one customer. If you assign a keyset already used with a customer to another customer, you’ll receive a 500 internal server error.

{
   "_tag": "InternalError"
}

Get a list of keyset IDs for your account

This endpoint allows you to get the list of keyset IDs assigned to the customers you’ve created in PubNub.

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

Sample request:

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

Sample response:

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

Generate a keyset ID for your account

This endpoint allows you to create a keyset ID that you can assign to your customers you’ve created in PubNub.

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

Sample request:

curl --request POST 'https://admin.pubnub.com/api/keys' \
--header 'X-Session-Token: <session_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "app_id" : <app_id>,
   "type": 1|0,  // 1 - production, 0 - testing
   "properties" : {
       "name" : <key_name>, // Name of the keyset
       "history" : 1|0,
       "message_storage_ttl" : 1...365,
       "lms" : 1|0,
       "max_message_size" : 1800 ... 7200,
       "multiplexing" : 1|0, // Stream Controller
       "apns" : 1|0,
       "uls" : 1|0, // Access Manager
show all 38 lines

Sample response:

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

Embedding scenarios

Following are a few common patterns in how partners can embed and expose Illuminate functionality to their customers. These scenarios illustrate different levels of control and customization, depending on your business model and the end-customer’s needs.

Customers can only modify the values in the decision rules

In this setup, you create and manage all Illuminate resources — Business Objects, Dashboards, and Decisions — within the PubNub Admin Portal. You then embed only the Decision Rules UI into your portal or site. You only allow your customers to modify rule values (e.g., thresholds, percentages, toggles) but do not give them access to the underlying conditions and actions configured, Business Objects, or Dashboards. Optionally, read-only dashboards can be exposed to give customers visibility into performance without edit capabilities.
Customers have full control

Here, you offer your customers full access to all Illuminate resources. The complete Illuminate UI — including Business Objects, Dashboards, and Decisions — is embedded in your portal or site. Customers can create, update, and manage their own logic, metrics, and visualizations, with permissions configurable as read-only or read/write depending on the user. This model suits those offering a self-service or power-user experience.
Customers can create and manage decisions

In this hybrid model, you define Business Objects, Dashboards, and core logic structures in the PubNub Admin Portal. The full Decisions section is embedded into your portal or site, allowing customers to create new decisions, configure available conditions and actions, and adjust rule values — while restricting access to Business Objects and Dashboards. This gives customers a flexible way to experiment and iterate, without exposing foundational data structures.

Illuminate offers a flexible embedding model that supports a range of access patterns — these are just a few of the most common. You can tailor what each customer sees and controls, making it easy to align with different product strategies or user needs. If you need more information, talk to our experts

Prerequisites​

Set up your PubNub account​

Set up customers and keysets​

Use Partner Portal​

Use API​

Embed the Illuminate UI​

Retrieve the access token​

Set required permissions​

Insert UI in your HTML​

Create Illuminate resources for your customers​

Errors​

Partner API endpoints​

Generate the x-session-token​

Get the app ID assigned to your customer​

Get the PubNub-generated unique customer ID​

Create a customer in PubNub​

Assign keysets to customers created in PubNub​

Get a list of keyset IDs for your account​

Generate a keyset ID for your account​

Embedding scenarios​

Prerequisites

Set up your PubNub account

Set up customers and keysets

Use Partner Portal

Use API

Embed the Illuminate UI

Retrieve the access token

Set required permissions

Insert UI in your HTML

Create Illuminate resources for your customers

Errors

Partner API endpoints

Generate the x-session-token

Get the app ID assigned to your customer

Get the PubNub-generated unique customer ID

Create a customer in PubNub

Assign keysets to customers created in PubNub

Get a list of keyset IDs for your account

Generate a keyset ID for your account

Embedding scenarios