Skip to main content
POST
Provision an embed user
πŸ”’ Admin only. Requires administrator privileges β€” the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role. Creates or updates one embed user from the identity your own system knows. An embed user is otherwise created the first time they generate a session, so this is how an integration puts its own directory into Cube up front: a user provisioned here is immediately addressable β€” listable, searchable, assignable to groups, and selectable wherever the product offers a choice of users β€” before they have ever opened the embed. Idempotent, and the body is the desired state: provisioning an externalId that already exists updates it rather than failing. email, userProfile.displayName and userProfile.picture are overwritten when supplied and preserved when omitted; each group lane is REPLACED when supplied, preserved when omitted, and cleared by []. The embed tenant itself is created on demand, so it need not exist yet. Everything set here is exactly what generate-session would have set, and a later session for the same externalId re-applies whatever it carries β€” so provisioning changes when a user exists, never what their session grants them.

Authorizations

Authorization
string
header
required

Token authentication. Send Authorization: Bearer <YOUR_TOKEN>.

Path Parameters

embedTenantName
string
required

Name of the embed tenant (the embedTenantName used to generate embed sessions).

Body

application/json

ProvisionEmbedUserInput

externalId
string
required

The id your own system knows this user by β€” the same externalId you will pass to generate-session. Trimmed and lowercased before it is stored, so casing never produces a second user.

Minimum string length: 1
email
string<email> | null

Email address, shown wherever the user is listed and searchable through GET /embed-tenants/{embedTenantName}/users. Must be a valid address, and is stored lowercased. Omit it and Cube derives a synthetic {externalId}@cubecloud.dev placeholder instead, which is what makes a user hard to recognise in a list. Supplying it again later updates the stored address.

groups
string[] | null

Global, account-wide groups (the groups field of generate-session) that gate data-model access. They must already exist. Supplying the field REPLACES the user’s global groups; omit it to leave them untouched, pass [] to clear them.

tenantGroups
string[] | null

Groups belonging to this embed tenant (the tenantGroups field of generate-session), which scope content sharing and organization within the tenant. Create them first via POST /embed-tenants/{embedTenantName}/groups. Supplying the field REPLACES the user’s tenant groups; omit it to leave them untouched, pass [] to clear them.

userProfile
object | null

Display name and avatar. displayName is the name shown wherever the user appears, including on content they author. Omitted fields keep their current value.

Response

200 - application/json
id
integer
required
username
string
required
createdAt
email
string | null
externalId
string | null
firstName
string | null
lastLogin