Generate Session

The Generate Session API provides secure, session-based authentication for signed embedding. This API creates temporary sessions that allow external users to access embedded dashboards and visualizations without exposing your API keys.

Authentication

The Generate Session API requires your Cube Cloud API key for authentication.

Endpoint

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

Request Headers

Request Body

User attributes

userAttributes is an array of { name, value } pairs that drive row-level security in queries.

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

Attribute definition lookup:

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

Rules:

• 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 is an array of group names (not IDs) that the user should belong to. Group definitions must already exist (or be created in the same request via groupDefinitions in creator mode).

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

Behavior:

Group definition lookup:

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

If any name in groups cannot be resolved, the request fails with Groups with names <missing> not found.

Creator mode: bootstrapping groups and user attributes

In API-first integrations you often want to mint an embed session and define the groups/attributes it references in a single call, without first making a round trip to the admin UI. The groupDefinitions and userAttributeDefinitions fields do that — they idempotently upsert definitions in the embed tenant’s scoped tables and are validated before groups and userAttributes are applied.

Both fields:

• 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" }
  ]
}

Duplicate name entries within the same request are rejected.

userAttributeDefinitions

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

type is immutable. If a definition with the supplied name already exists with a different type, the request fails with cannot change type and nothing is upserted. This protects every value already stored against that attribute from silently becoming invalid. To change the type, delete the attribute via the embed-tenant admin API and recreate it.

Duplicate name entries within the same request are rejected.

Bootstrap example

Define a group and an attribute, assign the user to both, and mint a session — all in one call:

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' }],
    }),
  },
);

A second call with the same body produces the same end state: the group and attribute already exist, descriptions/display names are reconciled if they changed, and the user’s memberships and values are re-applied.

Embed-tenant admin API

To list or delete the groups and attributes that have been bootstrapped into an embed tenant, use the admin endpoints scoped to that tenant:

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}

These endpoints use the same Api-Key authentication as Generate Session and require admin access. List endpoints return cursor-paginated results (?first=, ?after=).

Response

The API returns a session object:

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

Use the sessionId directly in your embed URL to authenticate and load content securely.

Code Example

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();

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']

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"]
  }'

Use session ID in signed embedding.