> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-claude-gallant-ramanujan-an09zv.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: Folders
  - name: Reports
  - name: Workbooks
  - 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:
        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.
        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.
      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 <YOUR_TOKEN>`.'

````