---
source_url: https://www.pubnub.com/docs/illuminate/embed-illuminate-ui
title: Embed Illuminate UI into partner sites
updated_at: 2026-06-01T12:03:05.374Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Embed Illuminate UI into partner sites

Embed Illuminate in your app or customer portal. Users get real‑time decisions, rules, and analytics in a familiar UI. This integration supports Original Equipment Manufacturer (OEM) and reseller models, where Illuminate functions as a native part of your product offering.

These steps show how to create tokens, set permissions, and embed the UI. See [Embedding scenarios](#embedding-scenarios) at the end for common patterns.

## Prerequisites

Before embedding, set up your PubNub account for partner integration and define your customer setup.

Enable partner features and create customer records with keysets for the embedded UI.

### Set up your PubNub account

Follow these steps:

1. Create and set up your account in the PubNub [Admin Portal](https://admin.pubnub.com).
2. After you create your account, ask [PubNub Support](https://support.pubnub.com/) or your account executive to enable the Partner feature.

### Set up customers and keysets

Set up customers and keysets in the Partner Portal or by API.

#### Use Partner Portal

1. 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.
2. 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](https://support.pubnub.com/) or your assigned account representative for more information.

## Embed the Illuminate UI

Generate a token. Then embed an iframe.

Generate customer access tokens with permissions. Embed the UI with an iframe. Optionally, create resources.

Use the API endpoints below to manage the integration programmatically.

### Retrieve the access token

Generate a secure access token for each customer. The token authenticates API requests and controls access in the embedded UI.

On customer login, call the API to get the access token. Next step: use this access token to embed the iframe.

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

The response includes an `accessToken`. Use it in later API calls and in the embedded UI. PubNub verifies that keysets under the `appId` belong to the customer.

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

Sample request to get the access token:

```bash
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",
       "decision:write",
       "decision:update:activation",
       "decision:write:config",
       "decision:update:rule",
       "metric:read",
       "metric:write"
   ],
 "expiresIn": "24h",
 "externalId": "0123CUSTOMER",
 "accountId": 123456,
 "appId": 12345678
}'

Sample response with the access token: 
{
   "accessToken": "222a22bc-333d-40ef-gh55-6ij777k08888"
}
```

### Set required permissions

Token permissions control what your customer can do. Choose permissions to match their needs.

* To give a user complete read and 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 table below lists more granular permissions. For example:

* To let users edit rules but not decision config, include `decision:update:rule` only.
* 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](https://www.pubnub.com/docs/illuminate/decisions/basics#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](https://www.pubnub.com/docs/illuminate/decisions/basics#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

Embed the UI by inserting an `iframe` with the [access token](#retrieve-the-access-token).

```html
<iframe src="https://oem.pubnub.com/embed/<Illuminate-resource>?embed=true&token=<token>&primaryColor=d02129&secondaryColor=007594&backgroundColor=ffffff&surfaceColor=f8f9fa&textPrimaryColor=212529&textSecondaryColor=6c757d" />
```

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](#retrieve-the-access-token) |
| Colors | Brand the UI with six hex colors: |

![Color codes](https://www.pubnub.com/assets/images/color-codes-5bf019a3b4542d4629acc1f88b2c62c8.png)

### Create Illuminate resources for your customers

Create resources for a selected customer in the PubNub Admin Portal, or in your site.

![Select customer in Admin Portal to create resources](https://www.pubnub.com/assets/images/select-customer-ad13154d2b3c4493c8ea93b96cf5798d.png)

## Errors

Error responses help you resolve issues during embedding and API calls.

* 401 Unauthorized — renew the token.
* 403 Forbidden — check `appId`, `customerId`, `keysetId`.
* 400 Bad Request — fix required fields or malformed JSON.
* 500 Internal Server Error — contact [PubNub Support](https://support.pubnub.com/).
* "There was a problem loading your..." — grant read/write permissions for that 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](https://support.pubnub.com/) 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`

```bash
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:

```bash
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](#get-the-pubnub-generated-unique-customer-id). |

Sample request:

```bash
{
   "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:

```bash
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:

```bash
{
   "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
       }
   ]
}
```

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

```bash
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:

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

Sample response:

```bash
{
   "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.

```bash
{
   "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:

```bash
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:

```bash
{
   "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"
           }
       ]
   }
}
```

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.

```bash
{
   "_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:

```bash
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:

```bash
{
   "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:

```bash
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
       "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>,       // If you modify the already set up region, you risk losing the existing files.
       "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, // Message persistence - Include presence events
       "wildcardsubscribe": 1|0,
       "objects_ref_integrity" : 1|0 // Whether to enable objects referential integrity
   }
}'
```

Sample response:

```bash
{
   "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.

1. 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.
2. 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.
3. 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