Generate Session

​

Authentication

​

Endpoint

POST https://{accountName}.cubecloud.dev/api/v1/embed/generate-session

​

Request Headers

​

Request Body

​

Response

{
  "sessionId": "abc123def456..."
}

​

Session settings

{
  "settings": {
    "allowAi": false,
    "showWorkbookShare": false
  }
}

​

Branch selection

• a name that isn’t a branch of the deployment returns 404;
• a branch nothing is serving returns 400. A branch is served while someone has it open in Cube, or permanently once its staging environment is enabled.

​

User profile

{
  "userProfile": {
    "displayName": "Jane Query",
    "picture": "https://example.com/avatars/jq.png"
  }
}

• Both fields are persisted on the external user (keyed by externalId).
• Sending userProfile on subsequent generate-session calls overwrites the previously-saved values.
• Omitting userProfile (or omitting a property inside it) preserves whatever was saved before.

​

Picture format

• Prefer HTTPS URLs — mixed-content rules will block http:// images on HTTPS embed pages.
• Keep the image under ~1 MB and ideally square (e.g. 96×96 or 256×256). Avatars are displayed in small containers, so anything larger is wasted bandwidth.
• The URL must be publicly reachable — signed URLs that expire or assets behind auth headers will not load.
• If the URL fails to load for any reason (404, wrong content type, CORS, network error), the UI gracefully falls back to an initials avatar derived from displayName. No error is returned to the caller.

​

User attributes

{
  "userAttributes": [
    { "name": "department", "value": "Sales" },
    { "name": "tier", "value": 2 },
    { "name": "regions", "value": ["us-east", "eu-west"] },
    { "name": "thresholds", "value": [10, 25, 50] }
  ]
}

• 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.
• 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.

• Duplicate name entries are rejected with 400 Bad Request.
• Values are persisted per user. Subsequent calls with the same externalId overwrite previous values for the supplied names.

​

Groups

{ "groups": ["analysts", "marketing"] }

• 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.
• Creator mode: names are resolved against the embed tenant’s scoped groups (embed_user_groups). Use groupDefinitions in the same request to upsert them.

​

Creator mode: bootstrapping groups and user attributes

• Require creatorMode: true.
• Require an embedTenantName (definitions are only meaningful inside an embed tenant).
• Require the useCreatorMode tenant flag — contact support to enable.
• Land in the embed-tenant scope only — they never modify tenant-wide groups or attributes.
• Are idempotent: running the same request twice produces the same end state.

​

groupDefinitions

{
  "groupDefinitions": [
    { "name": "analysts", "description": "Read-only viewers" },
    { "name": "marketing" }
  ]
}

​

userAttributeDefinitions

{
  "userAttributeDefinitions": [
    {
      "name": "department",
      "type": "string",
      "displayName": "Department",
      "defaultValue": "Unassigned",
      "description": "Org unit"
    }
  ]
}

​

Bootstrap example

const session = await fetch(
  `https://${ACCOUNT_NAME}.cubecloud.dev/api/v1/embed/generate-session`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Api-Key ${API_KEY}`,
    },
    body: JSON.stringify({
      deploymentId: DEPLOYMENT_ID,
      externalId: "user-123",
      embedTenantName: "acme-corp",
      creatorMode: true,

      // Upserted before validation runs
      groupDefinitions: [
        { name: "analysts", description: "Read-only viewers" },
      ],
      userAttributeDefinitions: [
        { name: "department", type: "string", displayName: "Department" },
      ],

      // Reference the names we just defined
      groups: ["analysts"],
      userAttributes: [{ name: "department", value: "Sales" }],
    }),
  }
);

​

Embed-tenant admin API

GET    /api/v1/embed-tenants/{embedTenantName}/groups
DELETE /api/v1/embed-tenants/{embedTenantName}/groups/{id}
GET    /api/v1/embed-tenants/{embedTenantName}/user-attributes
DELETE /api/v1/embed-tenants/{embedTenantName}/user-attributes/{id}

​

Code Example

import requests

API_KEY = 'YOUR_API_KEY'
ACCOUNT_NAME = 'your-account'

# Generate a session on your server
response = requests.post(
    f'https://{ACCOUNT_NAME}.cubecloud.dev/api/v1/embed/generate-session',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Api-Key {API_KEY}'
    },
    json={
        'deploymentId': 32,
        'externalId': 'user@example.com',
        'userAttributes': [
            {'name': 'department', 'value': 'Sales'}
        ],
        'groups': ['analysts']
    }
)

session_id = response.json()['sessionId']

const API_KEY = "YOUR_API_KEY";
const ACCOUNT_NAME = "your-account";

// Generate a session on your server
const response = await fetch(
  `https://${ACCOUNT_NAME}.cubecloud.dev/api/v1/embed/generate-session`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Api-Key ${API_KEY}`,
    },
    body: JSON.stringify({
      deploymentId: 32,
      externalId: "user@example.com",
      userAttributes: [{ name: "department", value: "Sales" }],
      groups: ["analysts"],
    }),
  }
);

const { sessionId } = await response.json();

curl -X POST "https://your-account.cubecloud.dev/api/v1/embed/generate-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -d '{
    "deploymentId": 32,
    "externalId": "user@example.com",
    "userAttributes": [
      {"name": "department", "value": "Sales"}
    ],
    "groups": ["analysts"]
  }'

​

Revoke a session

POST https://{accountName}.cubecloud.dev/api/v1/embed/session/revoke

curl -X POST "https://your-account.cubecloud.dev/api/v1/embed/session/revoke" \
  -H "Content-Type: application/json" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -d '{ "sessionId": "abc123def456..." }'