> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/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 `groups` and `userAttributes`, and an optional `securityContext`. Exchange the returned `sessionId` for a signed embed JWT via `POST /api/v1/embed/session/token` (single use).

`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 /v1/embed/generate-session
openapi: 3.1.0
info:
  title: Cube Cloud REST API
  version: 1.0.0
  description: >-
    Programmatically manage Cube Cloud: deployments and everything scoped to
    them

    (environments, folders, reports, workbooks, notifications, workspace, and
    agents),

    plus account-level users, groups, policies, embedding, and AI settings.
servers:
  - url: https://{tenant}.cubecloud.dev/api
    description: >-
      Cube Cloud API base URL. Replace the whole host if you use a custom
      domain.
    variables:
      tenant:
        default: your-tenant
        description: Your Cube Cloud tenant subdomain
security:
  - bearerAuth: []
tags:
  - name: Deployments
  - name: Environments
  - name: Folders
  - name: Reports
  - name: Workbooks
  - name: Notifications
  - name: Workspace
  - name: Embed
  - name: Embed Tenants
paths:
  /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-]{3,34}[a-z0-9]$
              type: string
            - type: 'null'
        embedTheme:
          oneOf:
            - $ref: '#/components/schemas/EmbedTheme'
              type: object
            - type: 'null'
        ephemeralTtlSeconds:
          oneOf:
            - type: number
            - type: 'null'
        externalId:
          oneOf:
            - type: string
            - type: 'null'
        groupDefinitions:
          oneOf:
            - items:
                $ref: '#/components/schemas/GroupDefinition'
              type: array
            - type: 'null'
        groups:
          oneOf:
            - items:
                type: string
              type: array
            - type: 'null'
        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:
            - type: object
              additionalProperties: true
            - type: 'null'
        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
    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
    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
                - 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
        - 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>`.'

````