Skip to main content
POST
/
v1
/
embed
/
generate-session
Generate an embed session
curl --request POST \
  --url https://{tenant}.cubecloud.dev/api/v1/embed/generate-session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "deploymentId": 123,
  "creatorMode": true,
  "email": "<string>",
  "embedTenantName": "<string>",
  "embedTheme": {
    "analyticsChat": {
      "backgroundColor": "<string>",
      "chatInput": {
        "backgroundColor": "<string>",
        "borderColor": "<string>"
      }
    },
    "chat": {
      "inputColor": "<string>"
    },
    "font": "<string>",
    "primaryColor": "<string>"
  },
  "ephemeralTtlSeconds": 123,
  "externalId": "<string>",
  "groupDefinitions": [
    {
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "groups": [
    "<string>"
  ],
  "internalId": "<string>",
  "isEphemeral": true,
  "publicDashboardId": "<string>",
  "roles": [
    "<string>"
  ],
  "securityContext": {},
  "userAttributeDefinitions": [
    {
      "name": "<string>",
      "defaultValue": "<string>",
      "description": "<string>",
      "displayName": "<string>"
    }
  ],
  "userAttributes": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "userProfile": {
    "displayName": "<string>",
    "picture": "<string>"
  }
}
'
{
  "sessionId": "<string>"
}
🔒 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.

Authorizations

​
Authorization
string
header
required

Token authentication. Send Authorization: Bearer <YOUR_TOKEN>.

Body

application/json

GenerateSessionDTO

​
deploymentId
number
required
​
creatorMode
boolean | null
​
email
string | null
​
embedTenantName
string | null
Pattern: ^[a-z][a-z0-9-]{3,34}[a-z0-9]$
​
embedTheme
object
​
ephemeralTtlSeconds
number | null
​
externalId
string | null
​
groupDefinitions
object[] | null
​
groups
string[] | null
​
internalId
string | null
​
isEphemeral
boolean | null
​
publicDashboardId
string | null
​
roles
string[] | null
​
securityContext
object
​
userAttributeDefinitions
object[] | null
​
userAttributes
object[] | null
​
userProfile
object

Response

200 - application/json
​
sessionId
string
required