docs: document undocumented customer-facing changes from the last week - #11677
docs: document undocumented customer-facing changes from the last week#11677keydunov wants to merge 1 commit into
Conversation
- Provisioning embed users ahead of their first session (POST
/embed-tenants/{embedTenantName}/user and /users)
- Cube Store's per-user WebSocket connection cap
(CUBESTORE_MAX_WS_CONNECTIONS_PER_USER)
- The AI Tokens Usage tab split into AI Usage and AI Requests
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Claude finished @keydunov's task in 2m 32s —— View job Review complete — docs-only, no blockers. 0 high, 2 medium, 2 low (4 inline comments).The Cube Store section is accurate against the Rust source; the two mediums are both in Full review
What I verifiedCube Store connection limits — accurate, no changes needed. Every claim in the new section checks out against
The anchor One thing the docs don't mention and arguably shouldn't: the counter fails open on lock timeout ( Findings
Notes
|
| rejected — and the embed tenant itself is created on demand if it doesn't | ||
| exist yet. | ||
|
|
||
| ### Response |
There was a problem hiding this comment.
### Response now reads as the provisioning endpoints' response.
### Response documents the Generate Session response ({ "sessionId": ... }). It was already awkwardly nested under ## Embed-tenant admin API, but before this PR it at least sat right after a short paragraph. Now it immediately follows a section that describes two POST endpoints and explicitly says the bulk one returns succeeded/failed — so a reader scrolling in lands on "Response → { "sessionId": ... }" and reasonably concludes that's what POST .../users returns.
Cheapest fix while you're in here: promote it back out of the admin-API section, e.g. rename to ## Generate Session response and move it above ## Embed-tenant admin API, or at minimum retitle it ### Generate Session response.
| The single-user endpoint takes one body with the same fields `generate-session` | ||
| accepts for an external user — `externalId`, `email`, `userProfile`, `groups`, | ||
| `tenantGroups` — so an integration uses one vocabulary whether it pushes its | ||
| directory ahead of time or lets a session provision the user. Session-only | ||
| fields (`userAttributes`, `securityContext`) aren't accepted here: a later | ||
| session re-applies them anyway, so provisioning can't be a second source of | ||
| truth for row-level security. `groups` and `tenantGroups` follow the same | ||
| replace-when-supplied, clear-with-`[]`, preserve-when-omitted rules as |
There was a problem hiding this comment.
tenantGroups isn't documented on this page — the framing and the #groups link both dead-end.
Two problems in this paragraph:
- It presents the accepted fields as "the same fields
generate-sessionaccepts for an external user —externalId,email,userProfile,groups,tenantGroups", buttenantGroupsappears nowhere else in this file: it's not a row in the Request Body table and not in the<Info>list of fields disallowed withinternalId. So the sentence's whole point ("one vocabulary") is undercut — the reader can't look the field up. It's only described inapi-reference/api.yamlandapi-reference/changelog.mdx. [Groups](#groups)resolves, but that section is exclusively aboutgroups(tenant-wide names,embed_user_groupsin creator mode). Sending the reader there fortenantGroupssemantics gives them the wrong scope, and the replace/clear/preserve table there never mentionstenantGroups.
Suggest adding a tenantGroups row to the Request Body table and a short paragraph under ## Groups (or a sibling ## Tenant groups) before pointing at it from here.
| Administrators can monitor token consumption on the billing settings page, | ||
| under two tabs: | ||
|
|
||
| - Total token usage over time | ||
| - Remaining allocation from per-seat grants and token packages | ||
| - Breakdown by usage dimension | ||
| - **AI Usage** — aggregate spend per user or per role over a billing period, | ||
| with a chart and a table. Covers the full period, not just recent activity. | ||
| - **AI Requests** — the raw request log, on a rolling window of hours with a | ||
| live tail of new requests as they come in. |
There was a problem hiding this comment.
The rewrite drops "remaining allocation" and nothing else on the page covers it.
The old bullet list included "Remaining allocation from per-seat grants and token packages" — that's the one thing an admin most wants from this page, and it's now unmentioned anywhere in the file. It matters directly for the very next section (## When limits are reached), which tells admins to go buy packages but never says where they can see how much is left. If the AI Usage tab still shows remaining balance, keep a clause for it.
Two smaller things:
- "on a rolling window of hours" is vague — say the actual window (e.g. "the last 24 hours") or drop the qualifier and just call it a live log of recent requests.
- AI Usage collides with the existing AI Usage dashboard in Usage Analytics. Same name, different surface. Worth a parenthetical here (or in the Usage Analytics row) so the two don't get confused — the BYOM line names the tabs with no location qualifier at all.
- "aggregate spend per user or per role" — the page is about tokens, and spend only applies to on-demand/contract customers. If the tab shows tokens with a cost column, say "token usage and cost".
| your own user directory, before their first session — use: | ||
|
|
||
| ```text | ||
| POST /api/v1/embed-tenants/{embedTenantName}/user |
There was a problem hiding this comment.
Nit / follow-up: neither POST /api/v1/embed-tenants/{embedTenantName}/user nor POST .../users is in docs-mintlify/api-reference/api.yaml — it currently only has GET /api/v1/embed-tenants/{embedTenantName}/users (listEmbedUsers, line 3047). Since that file is generated by scripts/extract-api.mjs from the enterprise repo, the prose here will be ahead of the OpenAPI reference until the next extraction. Not blocking, and the same is already true of the user-attributes endpoints listed just above, but worth a re-run so the two references agree — that's also where the bulk-action limit and the exact succeeded/failed shape would get pinned down.
Check List
Description of Changes Made
Weekly documentation audit against recent
cube-js/cubeandcubedevinc/cubejs-enterprisecommits, filtered against the customer-facing criteria. Three shipped features were
missing docs (or had gone stale):
POST /embed-tenants/{embedTenantName}/userand.../usersadmin endpoints let anintegration create/update embed users from its own directory before they ever
open the embed. Documented under the existing "Embed-tenant admin API" section
of the Generate Session reference.
CUBESTORE_MAX_WS_CONNECTIONS_PER_USERwas already in the environment variables reference but not cross-linked from the
Cube Store architecture page's connection/transport docs. Added a short
"Connection limits" subsection next to the existing "Message size limits" one.
referenced the old single "AI Tokens Usage" tab, which was split into two tabs
with different scopes (aggregate spend vs. raw request log). Updated the
"Tracking usage" section and a stale cross-reference in the BYOM docs.
All other candidate changes from the last week were checked and found already
documented (e.g.
COPY ... FROM STDIN, the queue fast-track flag,cube dbt sync,multi-sheet placements in the Sheets/Excel add-on) or not customer-facing
(internal instrumentation/analytics events).
Generated by Claude Code