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.

The Generate Session API is available on Premium and Enterprise plans.

</InfoBox>

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

Header	Value	Required
`Content-Type`	`application/json`	Yes
`Authorization`	`Api-Key YOUR_API_KEY`	Yes

Request Body

Field	Type	Required	Description
`externalId`	string	No	Unique identifier for the external user. Either `externalId` or `internalId` should be provided.
`internalId`	string	No	Email address of an internal Cube Cloud user. Either `externalId` or `internalId` should be provided.
`userAttributes`	array	No	Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`.
`groups`	string[]	No	Array of group names for user. Not allowed with `internalId`.
`securityContext`	object	No	Custom security context object passed to Cube queries. Not allowed with `internalId`.

When using internalId, the user must already exist in Cube Cloud. You cannot specify roles, groups, userAttributes, or securityContext with internalId — the internal user's existing permissions are used instead.

</InfoBox> <WarningBox>

Accounts are limited to 10,000 external users. To increase this limit, please contact support.

</WarningBox>

Response

The API returns a session object:

json

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

Field	Type	Description
`sessionId`	string	Unique session identifier to use for embedding content

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

Code Example

javascript

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({
      externalId: '[email protected]',
      userAttributes: [
        { name: 'department', value: 'Sales' }
      ]
    })
  }
);

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

python

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={
        'externalId': '[email protected]',
        'userAttributes': [
            {'name': 'department', 'value': 'Sales'}
        ]
    }
)

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

bash

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 '{
    "externalId": "[email protected]",
    "userAttributes": [
      {"name": "department", "value": "Sales"}
    ]
  }'

</CodeTabs>

Use session ID in signed embedding.