You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs-mintlify/embedding/iframe/creator-mode.mdx
+16-50Lines changed: 16 additions & 50 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,48 +7,29 @@ description: Embed the full Cube application so users can build and modify their
7
7
Creator Mode is available on the [Enterprise plan](https://cube.dev/pricing).
8
8
</Info>
9
9
10
-
Creator Mode lets you embed the entire Cube application into your product so users can create and modify their own dashboards directly within the embedded experience.
10
+
Creator Mode embeds the full Cube application instead of an individual dashboard or chat. Users can create and modify workbooks, dashboards, and reports inside the iframe.
11
+
12
+
To enable it, pass `creatorMode: true` to the [Generate Session API][ref-generate-session].
11
13
12
14
<Note>
13
15
Creator Mode requires [Signed embedding](/embedding/iframe/auth/signed). Private embedding is not supported.
14
16
</Note>
15
17
16
-
## How it works
17
-
18
-
In Creator Mode, you embed the full Cube application instead of individual dashboards or chat interfaces. This provides users with the complete Cube experience, including the ability to:
19
-
20
-
- Create new dashboards
21
-
- Modify existing dashboards
22
-
- Access all workbook and dashboard functionality
23
-
- Build custom analytics experiences
24
-
25
-
To enable Creator Mode, pass `creatorMode: true` to the [Generate Session API][ref-generate-session] when generating an embed session. Optionally, pass `embedTenantName` to scope content to a specific embed tenant — by default, creator mode uses the current tenant's name.
18
+
## Embed tenant scoping
26
19
27
-
## Embed tenant name
20
+
In Creator Mode, content (workbooks, dashboards) and the groups/user attributes referenced by the session are scoped to an **embed tenant**. Pass `embedTenantName` to isolate content per customer; omit it to use the current tenant.
28
21
29
-
`embedTenantName`is an optional parameter on the Generate Session API used to scope all content (dashboards, workbooks, etc.) that users create within the embedded application to a specific embed tenant. This ensures proper data isolation in multi-tenant scenarios.
22
+
`embedTenantName`must be lowercase, 5–36 chars, start with a letter, end with a letter or digit, and contain only `a-z`, `0-9`, or `-`.
30
23
31
-
When `embedTenantName` is omitted in creator mode, the session defaults to the current tenant, so most setups don't need to set it.
24
+
## Provisioning groups and user attributes
32
25
33
-
The value must be lowercase, start with a letter, end with a letter or number, and only contain letters, numbers, or hyphens (length 5–36).
26
+
In Creator Mode, `groups` and `userAttributes` resolve against the embed tenant's scoped catalog (separate from the tenant-wide one used by read-only embedding). To define those entries from your backend in the same call, pass `groupDefinitions` and `userAttributeDefinitions` — they are idempotent and validated before memberships and values are applied.
34
27
35
-
## Using Creator Mode
28
+
See [Generate Session → Creator mode bootstrap][ref-bootstrap] for the input shape, value types, and the immutable-`type` rule on attribute definitions.
36
29
37
-
To use Creator Mode and embed the app:
38
-
39
-
1.**Set the embed type to "App"** in the form
40
-
2.**Fill in Deployment ID** and either **External ID** or **Internal ID** (email). Optionally provide an **Embed Tenant Name** to scope content to a specific embed tenant
41
-
3.**Click "Generate Session & Embed"** — the request automatically includes `creatorMode: true` for app embeddings
42
-
4. The app is embedded at `/embed/d/{deploymentId}/app?session={sessionId}` and displayed in the iframe
43
-
44
-
Creator mode is enabled automatically when the embed type is "app"; no additional configuration is needed.
// Optional — defaults to the current tenant when omitted:
65
44
embedTenantName:"acme-corp",
45
+
creatorMode:true,
66
46
}),
67
47
},
68
48
);
69
49
70
-
constdata=awaitsession.json();
71
-
constsessionId=data.sessionId;
50
+
const { sessionId } =awaitsession.json();
72
51
```
73
52
74
-
### Embedding the app
75
-
76
-
Use the session ID to embed the full Cube application:
53
+
Embed the app with the returned session ID:
77
54
78
55
```html
79
56
<iframe
@@ -84,18 +61,7 @@ Use the session ID to embed the full Cube application:
84
61
></iframe>
85
62
```
86
63
87
-
Replace `{deploymentId}` with your deployment ID and `{sessionId}` with the session ID returned from the Generate Session API.
88
-
89
-
## Example application
90
-
91
-
For a complete working example of embedding, including Creator Mode, check out the [cube-embedding-demo](https://github.com/cubedevinc/cube-embedding-demo) repository. This demo application provides:
92
-
93
-
- A full working example of iframe embedding
94
-
- Implementation of signed iframe embedding with session generation
95
-
- Support for creator mode with an optional embed tenant name
96
-
- A React-based UI for testing embedding functionality
97
-
- Backend server that securely handles API key authentication
98
-
99
-
You can clone the repository, configure it with your Cube credentials, and run it locally to test embedding functionality or use it as a reference implementation for your own application.
64
+
For a complete working example, see the [cube-embedding-demo](https://github.com/cubedevinc/cube-embedding-demo) repository.
Copy file name to clipboardExpand all lines: docs-mintlify/reference/embed-apis/generate-session.mdx
+183-9Lines changed: 183 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,15 +32,21 @@ POST https://{accountName}.cubecloud.dev/api/v1/embed/generate-session
32
32
33
33
| Field | Type | Required | Description |
34
34
|-------|------|----------|-------------|
35
-
|`externalId`| string | No | Unique identifier for the external user. Either `externalId` or `internalId` should be provided. |
36
-
|`internalId`| string | No | Email address of an internal Cube Cloud user. Either `externalId` or `internalId` should be provided. |
37
-
|`userAttributes`| array | No | Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`. |
38
-
|`groups`| string[]| No | Array of group names for user. Not allowed with `internalId`. |
35
+
|`deploymentId`| number | Yes | ID of the deployment the session should grant access to. |
36
+
|`externalId`| string | Conditional | Stable identifier for the external user. Provide either `externalId` or `internalId` (not both). Must be lowercase and trimmed. |
37
+
|`internalId`| string | Conditional | Username of an existing internal Cube Cloud user. Provide either `externalId` or `internalId` (not both). The user must already exist. |
38
+
|`email`| string | No | Email to attach to the provisioned external user. Used only with `externalId`. |
39
+
|`embedTenantName`| string | No | Embed tenant to scope content to. Lowercase, 5–36 chars, must start with a letter and end with a letter or digit, only `a-z`, `0-9`, `-`. Defaults to the current tenant. |
40
+
|`creatorMode`| boolean | No | When `true`, mints a [creator-mode][ref-creator-mode] session and resolves groups/attributes against the embed tenant's scoped tables. Requires the `useCreatorMode` tenant flag. |
41
+
|`userAttributes`| array | No | Attribute values for row-level security. See [User attributes](#user-attributes). Not allowed with `internalId`. |
42
+
|`groups`| string[]| No | Group memberships for the user. See [Groups](#groups). Not allowed with `internalId`. |
43
+
|`userAttributeDefinitions`| array | No | Idempotently upsert attribute definitions before applying values. Requires `creatorMode: true`. See [Creator mode bootstrap](#creator-mode-bootstrapping-groups-and-user-attributes). |
44
+
|`groupDefinitions`| array | No | Idempotently upsert group definitions before assigning memberships. Requires `creatorMode: true`. See [Creator mode bootstrap](#creator-mode-bootstrapping-groups-and-user-attributes). |
39
45
|`securityContext`| object | No | Custom security context object passed to Cube queries. Not allowed with `internalId`. |
40
46
41
47
<Info>
42
48
43
-
When using `internalId`, the user must already exist in Cube Cloud. You cannot specify `roles`, `groups`, `userAttributes`, or `securityContext` with `internalId` — the internal user's existing permissions are used instead.
49
+
When using `internalId`, the user must already exist in Cube Cloud. You cannot specify `groups`, `userAttributes`, `groupDefinitions`, `userAttributeDefinitions`, or `securityContext` with `internalId` — the internal user's existing permissions are used instead.
44
50
45
51
</Info>
46
52
@@ -50,6 +56,167 @@ Accounts are limited to 10,000 external users. To increase this limit, please co
50
56
51
57
</Warning>
52
58
59
+
## User attributes
60
+
61
+
`userAttributes` is an array of `{ name, value }` pairs that drive row-level security in queries.
|`name`| string | Must reference an existing attribute definition (see lookup rules below). |
77
+
|`value`|`string`\|`number`\|`string[]`\|`number[]`\|`null`| The value type must match the definition's `type`. `null` clears the value. |
78
+
79
+
**Attribute definition lookup**:
80
+
81
+
-**Read-only mode** (`creatorMode` omitted or `false`): names are resolved against the tenant-wide attribute catalog (managed in **Settings → User Attributes** or via the admin GraphQL API). Any name not present there fails with `User attributes not found`.
82
+
-**Creator mode** (`creatorMode: true`): names are resolved against the embed tenant's scoped catalog (`embed_user_attributes`). Use `userAttributeDefinitions` in the same request to upsert definitions on the fly — see [Creator mode bootstrap](#creator-mode-bootstrapping-groups-and-user-attributes).
83
+
84
+
**Rules**:
85
+
86
+
- Duplicate `name` entries are rejected with `400 Bad Request`.
87
+
- Values are persisted per user. Subsequent calls with the same `externalId` overwrite previous values for the supplied names.
88
+
89
+
## Groups
90
+
91
+
`groups` is an array of group **names** (not IDs) that the user should belong to. Group definitions must already exist (or be created in the same request via `groupDefinitions` in creator mode).
92
+
93
+
```json
94
+
{ "groups": ["analysts", "marketing"] }
95
+
```
96
+
97
+
**Behavior**:
98
+
99
+
| Value | Effect |
100
+
|-------|--------|
101
+
| Field omitted (`undefined`) | Existing memberships are preserved. |
102
+
|`[]` (empty array) | All memberships are cleared. |
103
+
| Populated array | Memberships are replaced with exactly the supplied names. |
104
+
105
+
**Group definition lookup**:
106
+
107
+
-**Read-only mode**: names are resolved against tenant-wide groups (managed in **Settings → Groups** or via the admin GraphQL API). The membership row references the global group.
108
+
-**Creator mode**: names are resolved against the embed tenant's scoped groups (`embed_user_groups`). Use `groupDefinitions` in the same request to upsert them.
109
+
110
+
If any name in `groups` cannot be resolved, the request fails with `Groups with names <missing> not found`.
111
+
112
+
## Creator mode: bootstrapping groups and user attributes
113
+
114
+
In API-first integrations you often want to mint an embed session and define the groups/attributes it references in a single call, without first making a round trip to the admin UI. The `groupDefinitions` and `userAttributeDefinitions` fields do that — they idempotently upsert definitions in the embed tenant's scoped tables and are validated **before**`groups` and `userAttributes` are applied.
115
+
116
+
Both fields:
117
+
118
+
- Require `creatorMode: true`.
119
+
- Require an `embedTenantName` (definitions are only meaningful inside an embed tenant).
120
+
- Require the `useCreatorMode` tenant flag — contact support to enable.
121
+
- Land in the embed-tenant scope only — they never modify tenant-wide groups or attributes.
122
+
- Are idempotent: running the same request twice produces the same end state.
|`name`| string | Yes | Group name. Existing groups with this name are reused. |
138
+
|`description`| string | No | Updated when supplied and different from the stored value. Never cleared. |
139
+
140
+
Duplicate `name` entries within the same request are rejected.
141
+
142
+
### `userAttributeDefinitions`
143
+
144
+
```json
145
+
{
146
+
"userAttributeDefinitions": [
147
+
{
148
+
"name": "department",
149
+
"type": "string",
150
+
"displayName": "Department",
151
+
"defaultValue": "Unassigned",
152
+
"description": "Org unit"
153
+
}
154
+
]
155
+
}
156
+
```
157
+
158
+
| Property | Type | Required | Notes |
159
+
|----------|------|----------|-------|
160
+
|`name`| string | Yes | Attribute name. Existing attributes with this name are reused. |
161
+
|`type`| enum | Yes | One of `string`, `number`, `string_array`, `number_array`. **Immutable** — see below. |
162
+
|`displayName`| string | No | Updated when supplied and different from the stored value. |
163
+
|`defaultValue`| string | No | Updated when supplied and different from the stored value. |
164
+
|`description`| string | No | Updated when supplied and different from the stored value. |
165
+
166
+
**`type` is immutable.** If a definition with the supplied `name` already exists with a different `type`, the request fails with `cannot change type` and nothing is upserted. This protects every value already stored against that attribute from silently becoming invalid. To change the type, delete the attribute via the [embed-tenant admin API](#embed-tenant-admin-api) and recreate it.
167
+
168
+
Duplicate `name` entries within the same request are rejected.
169
+
170
+
### Bootstrap example
171
+
172
+
Define a group and an attribute, assign the user to both, and mint a session — all in one call:
A second call with the same body produces the same end state: the group and attribute already exist, descriptions/display names are reconciled if they changed, and the user's memberships and values are re-applied.
206
+
207
+
## Embed-tenant admin API
208
+
209
+
To list or delete the groups and attributes that have been bootstrapped into an embed tenant, use the admin endpoints scoped to that tenant:
210
+
211
+
```text
212
+
GET /api/v1/embed-tenants/{embedTenantName}/groups
These endpoints use the same `Api-Key` authentication as Generate Session and require admin access. List endpoints return cursor-paginated results (`?first=`, `?after=`).
0 commit comments