docs: pre-provisioning embed users via the embed-tenant admin API - #11695
docs: pre-provisioning embed users via the embed-tenant admin API#11695keydunov wants to merge 1 commit into
Conversation
cubejs-enterprise#14458 added POST /embed-tenants/{embedTenantName}/user
and its bulk sibling so embed users can be provisioned before their first
session, but the endpoints were never added to the Generate Session
reference alongside the existing groups/user-attributes admin endpoints.
|
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 1m 19s —— View job Review complete — docs-only change, no blockers. 4 issues (2 medium, 2 low), all posted inline.Full review
What's goodThe addition lands in the right file and the right section, follows the page's existing voice, and the semantics it documents are the ones readers actually get wrong — idempotency on Nothing security- or performance-relevant here; no code, tests, or navigation changes are implicated (this extends an existing page already registered in Findings
Note on verificationThe endpoint behavior described here originates in |
| POST /api/v1/embed-tenants/{embedTenantName}/users | ||
| ``` | ||
|
|
||
| The single-user endpoint takes the same identity fields as `generate-session` — `externalId`, `email`, `userProfile`, `groups`, `tenantGroups` — and is idempotent: provisioning an `externalId` that already exists updates it rather than failing. Each `groups`/`tenantGroups` lane is replaced when supplied, left untouched when omitted, and cleared with `[]`. A later session for the same `externalId` still applies whatever it carries, so provisioning only changes who a user is, never what their session grants. |
There was a problem hiding this comment.
tenantGroups is described here as one of "the same identity fields as generate-session", but it appears nowhere else on this page — the Request Body table (lines 33–53) documents externalId, email, userProfile, groups, userAttributes, etc., and never tenantGroups. A reader hits an undefined term with no way to learn what it means or how it differs from groups, and the "same fields as generate-session" framing is inaccurate as the page currently stands.
Either document tenantGroups in the Request Body table (if generate-session accepts it) or describe it inline here as a provisioning-only field.
| ```text | ||
| GET /api/v1/embed-tenants/{embedTenantName}/users | ||
| POST /api/v1/embed-tenants/{embedTenantName}/user | ||
| POST /api/v1/embed-tenants/{embedTenantName}/users | ||
| ``` |
There was a problem hiding this comment.
Two things about this block:
GET /api/v1/embed-tenants/{embedTenantName}/usersisn't mentioned in the PR description (which cites only the twoPOSTendpoints fromcubejs-enterprise#14458) and no prose below describes it — no response shape, and it's ambiguous whether the cursor-pagination sentence at line 282 (which precedes this subsection and refers to the groups/user-attributes lists) applies to it. Worth confirming it exists and, if it does, saying so explicitly.- Listing order doesn't match the prose: the paragraphs discuss single-user then bulk, but
GETleads. Reordering toPOST .../user,POST .../users,GET .../userswould track the narrative.
|
|
||
| The single-user endpoint takes the same identity fields as `generate-session` — `externalId`, `email`, `userProfile`, `groups`, `tenantGroups` — and is idempotent: provisioning an `externalId` that already exists updates it rather than failing. Each `groups`/`tenantGroups` lane is replaced when supplied, left untouched when omitted, and cleared with `[]`. A later session for the same `externalId` still applies whatever it carries, so provisioning only changes who a user is, never what their session grants. | ||
|
|
||
| The bulk endpoint accepts a `users` array (up to the account's bulk-action limit) and is partially successful: it returns `200` with a `succeeded` list and a `failed` list (each entry carrying the `externalId` and the error the single-user call would have returned), rather than failing the whole batch over one bad entry. |
There was a problem hiding this comment.
The new subsection is inserted directly above ### Response (line 298), which documents the generate-session response ({ "sessionId": "..." }). That heading was already sitting oddly under the ## Embed-tenant admin API H2, but this insertion makes the misreading much more likely: a reader finishes the bulk-provisioning paragraph, sees "### Response — The API returns a session object", and concludes the provisioning endpoints return a session.
Consider moving ### Response back up under the generate-session part of the page (or promoting it), so the admin-API section ends cleanly.
Related: the single-user POST response isn't documented at all here — only the bulk endpoint's shape is. Worth stating the status code and body it returns.
| The single-user endpoint takes the same identity fields as `generate-session` — `externalId`, `email`, `userProfile`, `groups`, `tenantGroups` — and is idempotent: provisioning an `externalId` that already exists updates it rather than failing. Each `groups`/`tenantGroups` lane is replaced when supplied, left untouched when omitted, and cleared with `[]`. A later session for the same `externalId` still applies whatever it carries, so provisioning only changes who a user is, never what their session grants. | ||
|
|
||
| The bulk endpoint accepts a `users` array (up to the account's bulk-action limit) and is partially successful: it returns `200` with a `succeeded` list and a `failed` list (each entry carrying the `externalId` and the error the single-user call would have returned), rather than failing the whole batch over one bad entry. |
There was a problem hiding this comment.
Two smaller gaps:
userAttributesis conspicuously absent from the identity-field list. It's a first-class generate-session field (line 44) and this very page's bootstrap example sets it, so readers will ask whether they can seed attribute values at provisioning time. State either way — silence reads as an oversight.- "up to the account's bulk-action limit" gives the reader nothing actionable: no number, no place to look it up, no indication of what happens on exceeding it (whole-request
400? partial?). Either quote the limit or link to where it's configured.
Style-wise, the rest of this page pairs each concept with a JSON/fetch example; a short request body for the bulk endpoint would fit the surrounding convention better than the two dense prose paragraphs.
Check List
Description of Changes Made
cubejs-enterprise#14458added two new admin endpoints for provisioning embed users ahead of their first session:These were never documented — the Generate Session reference page only listed the groups/user-attributes admin endpoints in its "Embed-tenant admin API" section. This adds a short "Provisioning users ahead of a session" subsection describing the request fields, idempotent/desired-state semantics, and the bulk endpoint's partial-success response shape, following the existing style on the page.
Generated by Claude Code