---
source_url: https://www.pubnub.com/docs/analytics/decisions/embed-ui-in-partner-sites
title: Embed the Illuminate UI in your portal
updated_at: 2026-09-30T07:20:08.000Z
---

# Embed the Illuminate UI in your portal

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

This guide shows you how to generate an access token for an end customer, configure their permissions, and embed the Illuminate UI in an HTML page using an iframe. The embedded `<iframe>` loads Illuminate's Business Objects, Decisions, or Dashboards scoped to a specific customer. Each customer sees only their own data. You can brand the UI with six hex colors.

## Before you start

Confirm you have:

* The partner feature enabled on your PubNub account. Contact [PubNub Support](https://support.pubnub.com/) or your account executive if it is not yet active.
* At least one customer record in PubNub with a keyset assigned to them. If not, follow [Create Illuminate resources for your customers](https://www.pubnub.com/docs/analytics/decisions/create-entities-as-partner.md) first.
* Your PubNub account ID. Find it in the [Admin Portal](https://admin.pubnub.com/) under your account settings.
* The external ID you assigned to the customer when you created their record.
* An HTML page or portal where you will insert the iframe.

## Generate an x-session-token

All API calls in this tutorial require an x-session-token. Generate one by calling the following endpoint with 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'"
}'
```

The response includes a session token. You will use it as the `x-session-token` header in all subsequent calls.

## Get your customer's app ID

The access token request requires the PubNub-generated app ID for the customer. Retrieve it in two calls.

### Get the customer ID

Your PubNub-generated customer ID is different from the external ID you assigned. Retrieve it:

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

Sample 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
    }
  ]
}
```

Note the `id` value. Use it in the next call.

### Get the app ID

```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>"
```

Sample response:

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

Note the `id` value. This is the `appId` for the access token request. If the customer has multiple app IDs, choose the one that holds the keysets you assigned to them.

## Choose permissions

Access tokens carry a permissions list that controls what the customer can do in the embedded UI.

* 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`.

For more granular control, choose individual permissions from the table below.

:::note Dependent permissions
Some permissions depend on `decision:update:activation`. Deactivating a Business Object or editing a metric that is tied to an active Decision requires that Decision to be deactivated first. Grant `decision:update:activation` alongside any permission that triggers a deactivation.
:::

| Resource | Permission | Access |
| --- | --- | --- |
| Business Object | `business-object:write` | Read and write access 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 and 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 the 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. |

## Retrieve an access token

On each customer login, call the API to generate a short-lived token. Use your x-session-token, the customer's external ID, your account ID, the app ID from the previous step, and the permissions you chose.

```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",
    "customerUserId": "user@example.com",
    "accountId": 123456,
    "appId": 12345678
  }'
```

Parameters:

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| externalId | string | Optional |  | Your unique customer ID, set when you created the customer record |
| customerUserId | string | Optional |  | Email address or unique identifier for the customer's user. Use email for visibility and audit. |
| accountId | number | Optional |  | Your PubNub account ID |
| appId | number | Optional |  | The app ID from [Get the app ID](#get-the-app-id) |
| permissions | string[] | Optional |  | Permissions array. See [Choose permissions](#choose-permissions). |
| expiresIn | string | Optional |  | Optional. A partner access token defaults to a 1-hour lifetime and can be set up to a maximum of 24 hours. |

PubNub verifies that keysets under the `appId` belong to the customer.

Sample response:

```json
{
  "accessToken": "222a22bc-333d-40ef-gh55-6ij777k08888"
}
```

Note the `accessToken` value. Use it in the next step.

## Embed the iframe

Add an `<iframe>` to your HTML page. Set the `src` to the Illuminate OEM endpoint, pass the access token, choose the Illuminate module to display, and set your brand colors.

```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" />
```

URL parameters:

| Parameter | Description |
| --- | --- |
| `Illuminate-resource` | The Illuminate module to display: `business-objects`, `dashboards`, or `decisions`. |
| `token` | The `accessToken` from the previous step. |
| `primaryColor` | Primary brand color as a hex code, without the `#` prefix. Example: `d02129`. |
| `secondaryColor` | Secondary brand color. Example: `007594`. |
| `backgroundColor` | Page background color. Example: `ffffff`. |
| `surfaceColor` | Card and surface background color. Example: `f8f9fa`. |
| `textPrimaryColor` | Primary text color. Example: `212529`. |
| `textSecondaryColor` | Secondary text color. Example: `6c757d`. |

Replace the example hex values with your brand's colors.

## Troubleshoot

If you encounter errors while embedding or after loading the iframe:

| Response | What to do |
| --- | --- |
| `401 Unauthorized` | Renew the access token. |
| `403 Forbidden` | Check `appId`, `customerId`, and `keysetId`. |
| `400 Bad Request` | Fix required fields or malformed JSON in your token request. |
| `500 Internal Server Error` | Contact [PubNub Support](https://support.pubnub.com/). |
| "There was a problem loading your..." | Grant read or write permissions for that Illuminate page in the token request. |

## Related tasks

* [Create Illuminate resources for your customers](https://www.pubnub.com/docs/analytics/decisions/create-entities-as-partner.md). Create or manage the Business Objects, Decisions, and Dashboards the customer sees in the embedded UI.
* [API operations for partners](https://www.pubnub.com/docs/analytics/decisions/partner-api-operations.md). Full reference for the partner API endpoints used in this guide.

Last updated at: 2026-09-30T07:20:08.000Z