Skip to content

docs: document embed user pre-provisioning and the split AI billing tabs #11711

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

Open
keydunov wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: document embed user pre-provisioning and the split AI billing tabs #11711

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
52aa2a0
docs: document embed user pre-provisioning and the split AI billing tabs
claude Sep 1, 2026
1e995ae
docs: document default deployment, dbt workspace validation, embed wo…
claude Sep 1, 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
12 changes: 7 additions & 5 deletions docs-mintlify/admin/account-billing/ai-tokens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,12 +75,14 @@ allowance resets at the start of each calendar month.

## Tracking usage

Administrators can monitor token consumption through the **AI Tokens Usage**
tab in the billing settings page. The dashboard shows:
Administrators can monitor token consumption on the **AI Usage** and **AI
Requests** tabs in the billing settings page:

- Total token usage over time
- Remaining allocation from per-seat grants and token packages
- Breakdown by usage dimension
- **AI Usage** shows spend per user or per role over a billing period, as a

@claude claude Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"spend" is ambiguous on this page — it's used a few lines up (line 55) for actual money, in "monthly on-demand spending limit". Here it means token consumption, which is what the sentence above it says ("monitor token consumption"). Suggest keeping the vocabulary consistent:

Suggested change
- **AI Usage** shows spend per user or per role over a billing period, as a
- **AI Usage** shows token consumption per user or per role over a billing
period, as a chart or table, including remaining allocation from per-seat
grants and token packages

chart or table, including remaining allocation from per-seat grants and
token packages
- **AI Requests** shows the underlying request log, with search and a live
tail of recent requests

## When limits are reached

Expand Down
19 changes: 19 additions & 0 deletions docs-mintlify/admin/deployment/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,25 @@ the **Cube Cloud** logo in the top left corner.
<img src="https://ucarecdn.com/cdd5831a-a8f8-4342-bc3e-25aab2c04a5b/" />
</Frame>

### Default deployment

If an account has more than one deployment, you can control which one people land
on when they open the workspace without navigating to a specific deployment
directly:

- **Account-wide** — an admin opens the **⋯** menu on a row in the deployments
list and chooses **Set as default** (or **Remove as default**). The pinned
deployment is marked with a home icon and becomes the landing deployment for
anyone who hasn't chosen one of their own.
- **Per user** — anyone can pin their own default from their account
**Preferences**, which takes precedence over the account-wide pin. The
deployment you most recently switched to also counts as a personal choice and
outranks the account pin, so it only applies until you actively switch to
something else.

Draft deployments are never candidates for either pin, and a pin you no longer
Comment on lines +28 to +37

@claude claude Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The precedence story is hard to follow as written:

  • The bullets run Account-wide → Per user, but resolution runs the other way (per-user pin, then most-recent, then account pin). The closing "skipped in favor of the next one in this order" then points back at a list that reads in the opposite direction of the order it means.
  • "The deployment you most recently switched to also counts as a personal choice and outranks the account pin, so it only applies until you actively switch to something else" — "it" has three candidate antecedents (the personal pin, the most-recent deployment, the account pin). Given "outranks the account pin", the intended subject seems to be the account pin, but the nearest noun is the wrong one.

An explicit ranked list would carry this better than prose, e.g.:

Cube picks the landing deployment in this order, skipping drafts and any deployment you no longer have access to:

  1. Your own default, pinned in account Preferences
  2. The deployment you most recently switched to
  3. The account-wide default, pinned by an admin from the ⋯ menu in the deployments list (marked with a home icon)

Fix this →

have access to is skipped in favor of the next one in this order.

## Creating a new deployment

Creating a new deployment is an essential prerequisite to running a Cube
Expand Down
9 changes: 7 additions & 2 deletions docs-mintlify/docs/explore-analyze/workbooks/calculated-fields.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,5 +147,10 @@ not.

### Editing a calculated field

Select a calculated field in the sidebar to open the editor. You can change its
**name** and **SQL expression**, then choose **Update** to apply.
Select a calculated field in the sidebar to open its editor. A field created by
the **bins** or **groups** panel reopens that same structured editor, letting you
change its **name** and **SQL expression**. Any other calculated field — a `CASE`
expression, a calculation like **% of total**, or a field saved to the workbook —
Comment on lines +150 to +153

@claude claude Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two problems in the structured-editor half of this sentence:

  1. "that same structured editor, letting you change its name and SQL expression" — "that same" points at the bins/groups panel described immediately above (line 144, "Edit bins… or Edit groups…"), but that panel edits boundaries, ranges, label style, group membership — not a raw SQL expression. The old text's "name and SQL expression" reads like it was carried over from the generic editor and reattached to the wrong one. If the structured editor really does expose a SQL box alongside the bins controls, worth saying so explicitly, since line 144 has just told the reader that panel is the structured alternative to hand-written SQL.

  2. This paragraph now overlaps the one at line 144–146, which already says only panel-generated fields offer Edit bins…/Edit groups…. Consider folding the two together rather than restating the same split from the other direction.

opens a SQL-only editor showing just its expression, since the field has no
structured form to round-trip. Edit the SQL and choose **Update** to apply; this
editor doesn't offer renaming.
21 changes: 21 additions & 0 deletions docs-mintlify/docs/integrations/dbt.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -612,6 +612,16 @@ credential can write to the repository — a `git-receive-pack` probe for a PAT,
| --- | --- |
| **Models path** | Directory in the dbt project where generated model files are written. Defaults to `models/marts/cube/`. |
| **Delivery mode** | **Open a pull request** (default) pushes to a `cube/dbt-push/*` branch and opens a PR/MR. **Commit directly to a branch** commits straight to a branch you name — validation still runs. |
| **Validation level** | How thoroughly a model is checked before it's committed: **Parse** only confirms the project still parses; **Compile** also compiles the generated SQL; **Build** additionally runs the model (and its tests) against your warehouse, in the **validation schema** below, so a broken model is caught before the PR opens. |

@claude claude Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding configurable validation levels leaves two earlier statements on this page describing only the Parse case as if it were the whole story:

  • Line 576 (section intro): "validated by a real dbt parse in Cube's sandbox before the PR is opened".
  • The Push step (line ~666): "runs dbt deps + dbt parse. If parse fails, the push stops with dbt's own output and no pull request is opened."

A reader who sets Build and then reads the Push step is told their model is only parsed. Both should generalize to "the configured validation level" and point back to this row — otherwise the page contradicts itself on what actually gains the PR its green status.

Fix this →

| **Validation schema** | Schema in your warehouse Cube builds into when validation level is **Build**. You own this schema — Cube never creates or drops it, and only the temporary relation created for that one validation run is cleaned up afterward. Required when validation level is **Build**. |

<Note>

**Build** currently runs on Snowflake, Amazon Redshift, PostgreSQL, and ClickHouse. On
Google BigQuery, Databricks, and Amazon Athena it falls back to **Parse** until
connection support for those warehouses is added.

</Note>

Then **Save dbt settings**.

Expand Down Expand Up @@ -659,6 +669,17 @@ hosts, a prefilled compare link to open it yourself.

</Steps>

### Author models from Analytics Chat

You can also drive the whole push loop from [the agent](/docs/explore-analyze/analytics-chat)
instead of the dialog above — for example, "turn this into a dbt model and open a PR." The
agent opens a live sandbox on your dbt project, drafts the model's `.sql` and `.yml`, and
runs the same validation configured above (parse, compile, or a full build against your
validation schema). It reports what it found and asks you to confirm before committing or
opening the pull request, using the delivery mode configured on the integration. Because the
sandbox stays open across the conversation, you can ask it to adjust the draft and
re-validate before you confirm.

### What gets pushed

Each push creates exactly two new files:
Expand Down
9 changes: 9 additions & 0 deletions docs-mintlify/embedding/iframe/creator-mode.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,15 @@ same as in a standalone dashboard embed. To hide any of its controls (title,
back button, Edit, Duplicate) for your embed, see
[Show or hide header controls](/embedding/iframe/dashboards#show-or-hide-header-controls).

## Workbook header controls

When a user opens a workbook (rather than a published dashboard) inside Creator
Mode, its header offers the same actions menu as the console: **Rename**,
**Duplicate**, **View all**, **New workbook**, and **Delete**. Rename and Delete
require the embed user's **Manage** permission on the workbook; Duplicate
requires **Manage** or **Edit**. Double-clicking the workbook name also renames
Comment on lines +29 to +31

@claude claude Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Manage and Edit are introduced here as named workbook permissions, but nothing else in docs-mintlify defines them — grep -rn "Manage" docs/explore-analyze/workbooks/ embedding/iframe/ matches only these two lines. An embed integrator reading this has no way to find out how an embed user acquires Manage vs Edit on a workbook. Worth linking to wherever workbook sharing/permissions are described (or to the group-based sharing model, since the section right below is about embed-tenant groups).

Also, the Dashboard header controls section directly above ends with a pointer to Show or hide header controls. This new section is silent on whether the workbook actions menu can be hidden the same way — a reader will reasonably assume it can. Worth saying either way.

it, the same as in the full Cube app.

## Embed tenant scoping

In Creator Mode, content (workbooks, dashboards) and the groups/user attributes referenced by the session are scoped to an **embed tenant**. Pass `embedTenantName` to isolate content per customer; omit it to use the current tenant.
Expand Down
15 changes: 15 additions & 0 deletions docs-mintlify/reference/embed-apis/generate-session.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -268,6 +268,21 @@ const session = await fetch(

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.

## Provisioning users ahead of their first session

An embed user is normally created only when they generate their first session — so you cannot add them to a group or share a workbook or dashboard with them until they have opened the embed at least once. To make a user addressable immediately, provision them directly:

```text
POST /api/v1/embed-tenants/{embedTenantName}/user
POST /api/v1/embed-tenants/{embedTenantName}/users
```

The singular endpoint provisions one user; the plural endpoint provisions up to 100 in a single request and is partially successful — it returns `succeeded` and `failed` arrays instead of failing the whole batch for one bad entry, with each failure keyed by `externalId`.

Each user takes the same fields as `generate-session` above — `externalId`, `email`, `userProfile`, `groups`, `tenantGroups` — except `userAttributes` and `securityContext`, which every session re-applies and so are not accepted here. Provisioning is idempotent: an existing `externalId` is updated rather than rejected, `email` and `userProfile` are overwritten only when supplied, and each group field is replaced when supplied, left untouched when omitted, and cleared with `[]`. Omit `email` and Cube derives a placeholder address instead, which makes the user harder to recognize in a list.

@claude claude Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tenantGroups is presented as one of "the same fields as generate-session above", but it doesn't appear anywhere above on this page — the Request Body table (lines 35–49) documents groups but not tenantGroups. A reader following the "above" pointer to find out what it means comes up empty.

It does exist in the API (api.yaml:8859, and GenerateSession accepts it per api-reference/changelog.mdx:199) — so the fix is to add the missing row to the Request Body table rather than to drop it here:

| tenantGroups | string[] | No | Per-embed-tenant groups for sharing and organizing content within a single embed tenant (creator mode), namespaced separately from the account-wide groups. |

Same page also omits tenantGroupDefinitions and embedTenantProfile from that table for the same reason.


These endpoints use the same `Api-Key` authentication as Generate Session and require admin access.
Comment on lines +271 to +284

@claude claude Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both endpoints are already documented in the generated API reference — provisionEmbedUser (api-reference/api.yaml:3048) and provisionEmbedUsers (:3147), including the 1–100 batch bound, the succeeded/failed shape, and per-field idempotency semantics. This section restates all of it in prose with no link between the two, so they'll drift.

Worth adding a link to the reference (e.g. /api-reference/embed-tenants/provisionembeduser) and trimming the per-field rules here to the pointer plus the one thing the reference doesn't convey — why you'd provision ahead of a session. That's also closer to the docs-mintlify guidance to say it once.

Two details the prose drops that are load-bearing:

  • The embed tenant is created on demand, so {embedTenantName} need not exist yet (api.yaml:3092).
  • tenantGroups entries must be created first via POST /embed-tenants/{embedTenantName}/groups (api.yaml:8867) — otherwise the call fails, and the admin-API section right below this one only documents GET/DELETE for groups.


## 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:
Expand Down