Provision an embed user
curl --request POST \
--url https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"externalId": "<string>",
"email": "jsmith@example.com",
"groups": [
"<string>"
],
"tenantGroups": [
"<string>"
],
"userProfile": {
"displayName": "<string>",
"picture": "<string>"
}
}
'import requests
url = "https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user"
payload = {
"externalId": "<string>",
"email": "jsmith@example.com",
"groups": ["<string>"],
"tenantGroups": ["<string>"],
"userProfile": {
"displayName": "<string>",
"picture": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
externalId: '<string>',
email: 'jsmith@example.com',
groups: ['<string>'],
tenantGroups: ['<string>'],
userProfile: {displayName: '<string>', picture: '<string>'}
})
};
fetch('https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'externalId' => '<string>',
'email' => 'jsmith@example.com',
'groups' => [
'<string>'
],
'tenantGroups' => [
'<string>'
],
'userProfile' => [
'displayName' => '<string>',
'picture' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user"
payload := strings.NewReader("{\n \"externalId\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"groups\": [\n \"<string>\"\n ],\n \"tenantGroups\": [\n \"<string>\"\n ],\n \"userProfile\": {\n \"displayName\": \"<string>\",\n \"picture\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"externalId\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"groups\": [\n \"<string>\"\n ],\n \"tenantGroups\": [\n \"<string>\"\n ],\n \"userProfile\": {\n \"displayName\": \"<string>\",\n \"picture\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"externalId\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"groups\": [\n \"<string>\"\n ],\n \"tenantGroups\": [\n \"<string>\"\n ],\n \"userProfile\": {\n \"displayName\": \"<string>\",\n \"picture\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"username": "<string>",
"createdAt": "2023-12-25",
"email": "<string>",
"externalId": "<string>",
"firstName": "<string>",
"lastLogin": "2023-12-25"
}Embed Tenants
Provision an embed user
POST
/
api
/
v1
/
embed-tenants
/
{embedTenantName}
/
user
Provision an embed user
curl --request POST \
--url https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"externalId": "<string>",
"email": "jsmith@example.com",
"groups": [
"<string>"
],
"tenantGroups": [
"<string>"
],
"userProfile": {
"displayName": "<string>",
"picture": "<string>"
}
}
'import requests
url = "https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user"
payload = {
"externalId": "<string>",
"email": "jsmith@example.com",
"groups": ["<string>"],
"tenantGroups": ["<string>"],
"userProfile": {
"displayName": "<string>",
"picture": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
externalId: '<string>',
email: 'jsmith@example.com',
groups: ['<string>'],
tenantGroups: ['<string>'],
userProfile: {displayName: '<string>', picture: '<string>'}
})
};
fetch('https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'externalId' => '<string>',
'email' => 'jsmith@example.com',
'groups' => [
'<string>'
],
'tenantGroups' => [
'<string>'
],
'userProfile' => [
'displayName' => '<string>',
'picture' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user"
payload := strings.NewReader("{\n \"externalId\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"groups\": [\n \"<string>\"\n ],\n \"tenantGroups\": [\n \"<string>\"\n ],\n \"userProfile\": {\n \"displayName\": \"<string>\",\n \"picture\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"externalId\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"groups\": [\n \"<string>\"\n ],\n \"tenantGroups\": [\n \"<string>\"\n ],\n \"userProfile\": {\n \"displayName\": \"<string>\",\n \"picture\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{tenant}.cubecloud.dev/api/v1/embed-tenants/{embedTenantName}/user")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"externalId\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"groups\": [\n \"<string>\"\n ],\n \"tenantGroups\": [\n \"<string>\"\n ],\n \"userProfile\": {\n \"displayName\": \"<string>\",\n \"picture\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"username": "<string>",
"createdAt": "2023-12-25",
"email": "<string>",
"externalId": "<string>",
"firstName": "<string>",
"lastLogin": "2023-12-25"
}🔒 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
Token authentication. Send Authorization: Bearer <YOUR_TOKEN>.
Path Parameters
Name of the embed tenant (the embedTenantName used to generate embed sessions).
Body
application/json
ProvisionEmbedUserInput
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:
1Email 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.
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.
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.
Display name and avatar. displayName is the name shown wherever the user appears, including on content they author. Omitted fields keep their current value.
Show child attributes
Show child attributes