> ## Documentation Index > Fetch the complete documentation index at: https://cubed3-claude-gallant-ramanujan-v3umyw.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Generate an embed session **πŸ”’ Admin only.** Requires administrator privileges β€” the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role. Creates a one-time embed session for a deployment and returns its `sessionId`. The session captures the embed context that will be baked into the embed token once redeemed β€” the target `deploymentId`, the end user's identity (`externalId` / `email` / `userProfile`), their group memberships, `userAttributes`, and an optional `securityContext`. Exchange the returned `sessionId` for a signed embed JWT via `POST /api/v1/embed/session/token` (single use). The end user can be assigned to two independent kinds of group, which serve different purposes: * **`groups`** β€” global, tenant-wide groups for **data-model access control**. Their names are passed verbatim into the Cube security context (`cubeCloud.groups`), where your data model's `access_policy` rules use them to gate cubes, views, members, and row-/column-level filters. They must already exist in the tenant. * **`tenantGroups`** β€” per-embed-tenant groups for **sharing and organizing content within a single embed tenant** (e.g. sharing a workbook or dashboard with a group in Creator Mode). Requires `creatorMode: true` and `embedTenantName`; create them inline via `tenantGroupDefinitions`. In the security context they are namespaced as `system:tenant:{embedTenantName}:group:{group}`, so they never collide with a same-named global group. See the individual request-body fields for the full contract. `deploymentId` is required and the caller must have read access to it. Embedding must be enabled for the tenant, otherwise `403` is returned. ## OpenAPI ````yaml /api-reference/api.yaml post /api/v1/embed/generate-session openapi: 3.1.0 info: title: Cube Platform API version: 1.0.0 description: >- Programmatically manage Cube: deployments and everything scoped to them (environments, folders, reports, workbooks, notifications, workspace, and agents), plus account-level users, groups, policies, embedding, and AI settings. Data-model authoring, dev mode, branches, and uploads live under /build/api/v1 β€” same host and token, routed to the build pods. servers: - url: https://{tenant}.cubecloud.dev description: Your tenant host. Replace the whole host if you use a custom domain. variables: tenant: default: your-tenant description: Your Cube tenant subdomain security: - bearerAuth: [] tags: - name: Deployments - name: Deployment Creation - name: Environments - name: Env Variables - name: Regions - name: Data Model - name: Data Model Uploads - name: GitHub - name: GitHub Connection - name: dbt Sync - name: Databricks Metric View Publication - name: Databricks Metric View Integration - name: Folders - name: Reports - name: Workbooks - name: Dashboard Exports - name: Notifications - name: Workspace - name: Users - name: Users Admin - name: User Attributes - name: User Attribute Values - name: Tenant Settings - name: OAuth Integrations - name: User OAuth Tokens - name: OIDC Token Configs - name: App Theme - name: Embed - name: Embed Tenants - name: Dashboard Embed Access - name: Usage Analytics - name: OpenAPI Spec paths: /api/v1/embed/generate-session: post: tags: - Embed summary: Generate an embed session operationId: generateSession requestBody: content: application/json: schema: $ref: '#/components/schemas/GenerateSession' description: GenerateSessionDTO required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/GenerateSessionResponse' description: '' components: schemas: GenerateSession: properties: creatorMode: oneOf: - type: boolean - type: 'null' deploymentId: type: number email: oneOf: - type: string - type: 'null' embedTenantName: oneOf: - pattern: ^[a-z][a-z0-9-]{0,34}[a-z0-9]$ type: string - type: 'null' embedTenantProfile: oneOf: - $ref: '#/components/schemas/EmbedTenantProfile' type: object - type: 'null' embedTheme: oneOf: - $ref: '#/components/schemas/EmbedTheme' type: object - type: 'null' externalId: oneOf: - type: string - type: 'null' groupDefinitions: oneOf: - items: $ref: '#/components/schemas/GroupDefinition' type: array - type: 'null' description: >- Deprecated and ignored. Global groups can no longer be created through this endpoint β€” define them beforehand via the Cube UI or admin API. Still accepted for backward compatibility (no error), but it has no effect. To create per-embed-tenant groups, use `tenantGroupDefinitions`. deprecated: true groups: oneOf: - items: type: string type: array - type: 'null' description: >- Global user groups β€” defined once at the tenant level and shared across every embed tenant β€” to assign this embed user to. Use `groups` for **data-model access control**: each name is placed verbatim into the Cube security context as `cubeCloud.groups`, where your data model's `access_policy` rules reference it to gate cubes, views, members, and row-/column-level filters. The groups must already exist in the tenant (create them via the Cube UI or admin API beforehand) β€” this endpoint never creates global groups, and names that do not resolve to an existing group are rejected. Global groups are NOT shown in an embed tenant’s Creator Mode UI. To share or organize content inside a single embed tenant, use `tenantGroups` instead. internalId: oneOf: - type: string - type: 'null' isEphemeral: oneOf: - type: boolean - type: 'null' publicDashboardId: oneOf: - type: string - type: 'null' roles: oneOf: - items: type: string type: array - type: 'null' securityContext: oneOf: - additionalProperties: true type: object - type: 'null' settings: oneOf: - $ref: '#/components/schemas/EmbedSessionSettings' type: object - type: 'null' description: >- Per-session overrides for embed behavior, stored in the signed embed token. Each documented key applies only to this session; omitted keys preserve their existing default behavior. tenantGroupDefinitions: oneOf: - items: $ref: '#/components/schemas/GroupDefinition' type: array - type: 'null' description: >- Idempotently create or update the per-embed-tenant groups referenced by `tenantGroups`, before they are assigned. Requires `creatorMode: true` and `embedTenantName`. Use this to declare a tenant’s groups in the same call that assigns them, so you do not need a separate admin request. Applies only to per-embed-tenant groups; global groups must be defined beforehand. tenantGroups: oneOf: - items: type: string type: array - type: 'null' description: >- Per-embed-tenant user groups β€” scoped to the single embed tenant named by `embedTenantName` β€” to assign this embed user to. Use `tenantGroups` for **content sharing and organization within one embed tenant**: for example, so a creator can share a workbook, dashboard, or folder with a group of that tenant’s users. These are the only groups shown in the embed tenant’s Creator Mode UI. Requires `creatorMode: true` and `embedTenantName`. Define the groups beforehand β€” or in the same request β€” via `tenantGroupDefinitions`. In the Cube security context they appear namespaced as `system:tenant:{embedTenantName}:group:{groupName}`, so a tenant group can never collide with β€” or be mistaken for β€” a global `groups` entry of the same name. For organization-wide data-model access policies, use `groups`. userAttributeDefinitions: oneOf: - items: $ref: '#/components/schemas/UserAttributeDefinition' type: array - type: 'null' userAttributes: oneOf: - items: $ref: '#/components/schemas/UserAttributeInput' type: array - type: 'null' userProfile: oneOf: - $ref: '#/components/schemas/EmbedUserProfile' type: object - type: 'null' required: - deploymentId type: object GenerateSessionResponse: properties: sessionId: type: string required: - sessionId type: object EmbedTenantProfile: properties: displayName: oneOf: - type: string - type: 'null' type: object EmbedTheme: properties: analyticsChat: oneOf: - $ref: '#/components/schemas/EmbedThemeAnalyticsChat' type: object - type: 'null' chat: oneOf: - $ref: '#/components/schemas/EmbedThemeChat' type: object - type: 'null' font: oneOf: - type: string - type: 'null' primaryColor: oneOf: - type: string - type: 'null' type: object GroupDefinition: properties: description: oneOf: - type: string - type: 'null' name: type: string required: - name type: object EmbedSessionSettings: properties: allowAi: oneOf: - type: boolean - type: 'null' description: >- Whether this session may use AI at all. This is the master switch over every AI surface in the embed: the dashboard agent, the workbook chat, the AI summary widgets and the standalone embedded chat. Omit to inherit the account-wide embed setting (allowed by default); `false` disables AI even if it is enabled account-wide. Unlike the `show*` keys below it is enforced server-side β€” the session cannot obtain AI Chat credentials at all, so no request made with it can consume AI tokens β€” and it outranks them: a `false` here disables a surface whose own `show*` key is `true`. It does not change user roles or permissions for non-AI API calls. `null` is accepted and means the same as omitting it. allowChatWorkspaceAuthoring: oneOf: - type: boolean - type: 'null' description: >- Whether AI Chat authenticated with this session may create or modify persistent Cube Workspace content. Set to `false` for headless chat integrations that render answers in their own UI: ad-hoc data analysis and inline tables/charts remain available, but the agent cannot save or update standalone explorations/reports, create or modify workbooks, create or publish dashboards, or direct users to those Cube UI surfaces. Omit or set to `true` to preserve the session user's role-derived authoring capabilities; `true` never grants access the user does not already have. This setting changes only AI Chat tools and instructions. It does not change user roles or permissions for direct API calls. locale: oneOf: - type: string - type: 'null' description: >- UI language for every embed viewed with this session, as a BCP-47 code β€” a full code (`es-ES`), a short code (`es`) or a regional variant all resolve to a shipped locale. Sits between the per-iframe `?locale=` parameter, which still wins because it is the more specific answer, and the account-wide default under Embed β†’ Settings. A language Cube does not ship falls through to that default rather than failing the session. showAiWidgets: oneOf: - type: boolean - type: 'null' description: >- Whether AI summary widgets are authorable and refreshable with this session: the "AI widget" entry in the dashboard editor's Add widgets menu, and the prompt input plus Generate/Regenerate controls on an existing widget. An already-generated summary still renders, so a published dashboard keeps its content β€” it simply cannot be regenerated. Omit to inherit the account-wide embed setting (enabled by default); `false` disables them even if they are enabled account-wide, `true` enables them even if they are disabled account-wide. showDashboardChat: oneOf: - type: boolean - type: 'null' description: >- Whether embedded published dashboards viewed with this session show the AI chat (agent panel and launcher bubble). Omit to inherit the account-wide embed setting (shown by default); `false` hides the chat even if it is enabled account-wide, `true` shows it even if it is disabled account-wide. Only affects the dashboard surface, and only hides the entry point β€” use `allowAi` to withhold AI from the session. showDashboardSettings: oneOf: - type: boolean - type: 'null' description: >- Whether the dashboard editor viewed with this session offers its settings panel β€” the gear button and the sidebar behind it. That panel is the ONLY place an embed user can reach the dashboard slug, the per-dashboard time zone, the per-dashboard agent, the grid behaviour switches and the dashboard theme, so `false` withdraws all of them together. Omit or set to `true` to keep the panel (the default). showGroupByCube: oneOf: - type: boolean - type: 'null' description: >- Whether the workbook data pane viewed with this session offers the "Group by Cube" / "Group by Folder" item in its more-actions menu. `false` hides the item AND pins the pane to the grouping it would have defaulted to β€” by folder when the view defines folders, by cube otherwise. The choice is remembered per browser, so pinning is what makes the pane look the same for every user of the session rather than freezing whatever each of them last picked. No content is withdrawn either way. Omit or set to `true` to leave the choice with the user (the default). showMemberNames: oneOf: - type: boolean - type: 'null' description: >- Whether the workbook data pane viewed with this session may display raw member NAMES instead of their titles (the "Show Member Names" item in the pane's more-actions menu). Member names are the data model's own identifiers, so this is a schema-protection setting in the same family as the account-wide Show Generated SQL switch. `false` hides the menu item AND pins the pane to titles, so a user who already switched to names is returned to titles β€” hiding the control alone would leave them stuck on names with no way back. Omit or set to `true` to leave the choice with the user (the default). showWorkbookChat: oneOf: - type: boolean - type: 'null' description: >- Whether the Creator Mode workbook viewed with this session shows its AI entry points: the chat side panel and its toggle, the launchpad's "Ask Cube Agent" button and the "Fix in chat" action on a failed report. Omit to inherit the account-wide embed setting (shown by default); `false` hides them even if they are enabled account-wide, `true` shows them even if they are disabled account-wide. Hides entry points only β€” use `allowAi` to withhold AI from the session. showWorkbookShare: oneOf: - type: boolean - type: 'null' description: >- Whether the Creator Mode workspace viewed with this session offers sharing: the workbook header's Share button and the Share action on a workbook, dashboard, exploration or folder row in the workspace list. Set to `false` for a deployment where each embed user should only ever see their own content. Omit or set to `true` to keep sharing available (the default). Hides the entry points only β€” it does not revoke access already granted, and it never widens what the session's own permissions allow. timezone: oneOf: - type: string - type: 'null' description: >- IANA time zone the agent runs its queries in for every embed viewed with this session (e.g. `America/New_York`). Sits between the per-iframe `?timezone=` parameter and the account-wide default, and remains subject to the tenant time-zone policy β€” it is not a way around it. A bare UTC offset or an unknown name falls through to the account default rather than failing the session, because Cube would compute in UTC and report nothing. type: object UserAttributeDefinition: properties: defaultValue: oneOf: - type: string - type: 'null' description: oneOf: - type: string - type: 'null' displayName: oneOf: - type: string - type: 'null' name: type: string type: $ref: '#/components/schemas/UserAttributeDefinitionDTOType' required: - name - type type: object UserAttributeInput: properties: name: type: string value: oneOf: - oneOf: - type: string - type: number - type: boolean - items: type: string type: array - type: array items: type: number - type: 'null' required: - name type: object EmbedUserProfile: properties: displayName: oneOf: - type: string - type: 'null' picture: oneOf: - format: url type: string - type: 'null' type: object EmbedThemeAnalyticsChat: properties: backgroundColor: oneOf: - type: string - type: 'null' chatInput: oneOf: - $ref: '#/components/schemas/EmbedThemeAnalyticsChatInput' type: object - type: 'null' type: object EmbedThemeChat: properties: inputColor: oneOf: - type: string - type: 'null' type: object UserAttributeDefinitionDTOType: enum: - string - number - boolean - string_array - number_array type: string EmbedThemeAnalyticsChatInput: properties: backgroundColor: oneOf: - type: string - type: 'null' borderColor: oneOf: - type: string - type: 'null' type: object securitySchemes: bearerAuth: type: http scheme: bearer description: 'Token authentication. Send `Authorization: Bearer `.' ````