Embed the Illuminate UI in your portal

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 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 first.
• Your PubNub account ID. Find it in the Admin Portal 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:

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

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:

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

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

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

Get the app ID

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

Sample response:

1{
2  "result": [
3    {
4      "id": 12345678,
5      "accountId": 123456
6    }
7  ]
8}

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.

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.

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:

Parameter	Description
externalId Type: string	Your unique customer ID, set when you created the customer record
customerUserId Type: string	Email address or unique identifier for the customer's user. Use email for visibility and audit.
accountId Type: number	Your PubNub account ID
appId Type: number	The app ID from Get the app ID
permissions Type: string[]	Permissions array. See Choose permissions.
expiresIn Type: string	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:

1{
2  "accessToken": "222a22bc-333d-40ef-gh55-6ij777k08888"
3}

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.

1<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.
"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. Create or manage the Business Objects, Decisions, and Dashboards the customer sees in the embedded UI.
• API operations for partners. Full reference for the partner API endpoints used in this guide.