Skip to content

[pull] master from cube-js:master #271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pull merged 2 commits into from
Jan 13, 2026
Merged

[pull] master from cube-js:master #271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
557b189
docs: internalUsername -> internalId rename
paveltiunov Jan 13, 2026
00d768f
docs: generate-session docs
paveltiunov Jan 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions docs/pages/product/apis-integrations/embed-apis/chat-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,16 +81,16 @@ while (true) {
|-------|------|----------|-------------|
| `input` | string | No | The user's message or question. If omitted returns current state of thread with provided chatId. |
| `chatId` | string | No | Chat thread ID. If omitted, a new thread is created automatically. If provided, it should match the previously returned `chatId` from a message with id `__cutoff__` sent as the `state.chatId` field. |
| `sessionSettings.externalId` | string | No | Unique identifier for the external user, lowercase and without spaces. Either `externalId` or `internalUsername` should be provided. |
| `sessionSettings.internalUsername` | string | No | Username of an internal Cube Cloud user. Either `externalId` or `internalUsername` should be provided. |
| `sessionSettings.externalId` | string | No | Unique identifier for the external user, lowercase and without spaces. Either `externalId` or `internalId` should be provided. |
| `sessionSettings.internalId` | string | No | Email of an internal Cube Cloud user. Either `externalId` or `internalId` should be provided. |
| `sessionSettings.email` | string | No | User's email address |
| `sessionSettings.userAttributes` | array | No | Array of `{name, value}` pairs for row-level security. Not allowed with `internalUsername`. |
| `sessionSettings.groups` | string[] | No | Array of group names the user belongs to. Not allowed with `internalUsername`. |
| `sessionSettings.securityContext` | object | No | Custom security context object passed to Cube queries. Not allowed with `internalUsername`. |
| `sessionSettings.userAttributes` | array | No | Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`. |
| `sessionSettings.groups` | string[] | No | Array of group names the user belongs to. Not allowed with `internalId`. |
| `sessionSettings.securityContext` | object | No | Custom security context object passed to Cube queries. Not allowed with `internalId`. |

<InfoBox>

When using `internalUsername`, the user must already exist in Cube Cloud. You cannot specify `roles`, `groups`, `userAttributes`, or `securityContext` with `internalUsername` — the internal user's existing permissions are used instead.
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>

Expand All @@ -103,8 +103,8 @@ User attributes must first be configured in your Cube admin panel before they ca
</InfoBox>

**Supported Fields:**
- `externalId` (optional): Unique identifier for the external user. Either `externalId` or `internalUsername` should be provided.
- `internalUsername` (optional): Username of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalUsername` should be provided.
- `externalId` (optional): Unique identifier for the external user. Either `externalId` or `internalId` should be provided.
- `internalId` (optional): Email of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalId` should be provided.
- `email` (optional): User's email address
- `userAttributes` (optional): Array of key-value pairs containing user metadata. Only available with `externalId`.

Expand Down Expand Up @@ -154,12 +154,12 @@ Copy the complete Chat API URL from your agent settings (**Chat API URL** field)
- **`input`** (string): User message or query to send to the AI agent, e.g. "What is our revenue last month?". If omitted, returns current state of thread with provided `chatId`.
- **`chatId`** (string): Chat thread ID. If omitted, a new thread is created automatically. If provided, it should match the previously returned `chatId` from a message with id `__cutoff__`.
- **`sessionSettings`** (object, required): Session configuration for the user
- **`externalId`** (string): Unique identifier for the external user. Either `externalId` or `internalUsername` should be provided.
- **`internalUsername`** (string): Username of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalUsername` should be provided.
- **`externalId`** (string): Unique identifier for the external user. Either `externalId` or `internalId` should be provided.
- **`internalId`** (string): Email of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalId` should be provided.
- **`email`** (string): User's email address
- **`userAttributes`** (array): Array of `{name, value}` pairs for row-level security. Not allowed with `internalUsername`.
- **`groups`** (string[]): Array of group names for user. Not allowed with `internalUsername`.
- **`securityContext`** (object): Custom security context object passed to Cube queries. Not allowed with `internalUsername`.
- **`userAttributes`** (array): Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`.
- **`groups`** (string[]): Array of group names for user. Not allowed with `internalId`.
- **`securityContext`** (object): Custom security context object passed to Cube queries. Not allowed with `internalId`.

## Response Format

Expand Down
19 changes: 11 additions & 8 deletions docs/pages/product/apis-integrations/embed-apis/generate-session.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,17 @@ POST https://{accountName}.cubecloud.dev/api/v1/embed/generate-session

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `externalId` | string | Yes | Unique identifier for the external user |
| `email` | string | No | User's email address |
| `userAttributes` | array | No | Array of `{name, value}` pairs for row-level security |
| `groups` | string[] | No | Array of group names for user |
| `securityContext` | object | No | Custom security context object passed to Cube queries |
| `externalId` | string | No | Unique identifier for the external user. Either `externalId` or `internalId` should be provided. |
| `internalId` | string | No | Email 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`. |

<InfoBox>

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>

Expand Down Expand Up @@ -76,7 +82,6 @@ const response = await fetch(
},
body: JSON.stringify({
externalId: 'user@example.com',
email: 'user@example.com',
userAttributes: [
{ name: 'department', value: 'Sales' }
]
Expand All @@ -102,7 +107,6 @@ response = requests.post(
},
json={
'externalId': 'user@example.com',
'email': 'user@example.com',
'userAttributes': [
{'name': 'department', 'value': 'Sales'}
]
Expand All @@ -118,7 +122,6 @@ curl -X POST "https://your-account.cubecloud.dev/api/v1/embed/generate-session"
-H "Authorization: Api-Key YOUR_API_KEY" \
-d '{
"externalId": "user@example.com",
"email": "user@example.com",
"userAttributes": [
{"name": "department", "value": "Sales"}
]
Expand Down