Provision Users

curl --request POST \
  --url https://api.xenia.team/api/v1/mgt/users/provision \
  --header 'Content-Type: application/json' \
  --header 'x-client-key: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data '
{
  "users": [
    {
      "email": "jane.smith@example.com",
      "role_id": "4ccf0b65-fb99-40da-92d6-3f98730df8b2",
      "location_ids": [
        "a13ddb59-3e5c-4bdd-8673-fc913b93b9db"
      ],
      "first_name": "Jane",
      "last_name": "Smith"
    }
  ],
  "location_mode": "add"
}
'

import requests

url = "https://api.xenia.team/api/v1/mgt/users/provision"

payload = {
    "users": [
        {
            "email": "jane.smith@example.com",
            "role_id": "4ccf0b65-fb99-40da-92d6-3f98730df8b2",
            "location_ids": ["a13ddb59-3e5c-4bdd-8673-fc913b93b9db"],
            "first_name": "Jane",
            "last_name": "Smith"
        }
    ],
    "location_mode": "add"
}
headers = {
    "x-client-key": "<api-key>",
    "x-client-secret": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-client-key': '<api-key>',
    'x-client-secret': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    users: [
      {
        email: 'jane.smith@example.com',
        role_id: '4ccf0b65-fb99-40da-92d6-3f98730df8b2',
        location_ids: ['a13ddb59-3e5c-4bdd-8673-fc913b93b9db'],
        first_name: 'Jane',
        last_name: 'Smith'
      }
    ],
    location_mode: 'add'
  })
};

fetch('https://api.xenia.team/api/v1/mgt/users/provision', 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://api.xenia.team/api/v1/mgt/users/provision",
  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([
    'users' => [
        [
                'email' => 'jane.smith@example.com',
                'role_id' => '4ccf0b65-fb99-40da-92d6-3f98730df8b2',
                'location_ids' => [
                                'a13ddb59-3e5c-4bdd-8673-fc913b93b9db'
                ],
                'first_name' => 'Jane',
                'last_name' => 'Smith'
        ]
    ],
    'location_mode' => 'add'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-client-key: <api-key>",
    "x-client-secret: <api-key>"
  ],
]);

$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://api.xenia.team/api/v1/mgt/users/provision"

	payload := strings.NewReader("{\n  \"users\": [\n    {\n      \"email\": \"jane.smith@example.com\",\n      \"role_id\": \"4ccf0b65-fb99-40da-92d6-3f98730df8b2\",\n      \"location_ids\": [\n        \"a13ddb59-3e5c-4bdd-8673-fc913b93b9db\"\n      ],\n      \"first_name\": \"Jane\",\n      \"last_name\": \"Smith\"\n    }\n  ],\n  \"location_mode\": \"add\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-client-key", "<api-key>")
	req.Header.Add("x-client-secret", "<api-key>")
	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://api.xenia.team/api/v1/mgt/users/provision")
  .header("x-client-key", "<api-key>")
  .header("x-client-secret", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"users\": [\n    {\n      \"email\": \"jane.smith@example.com\",\n      \"role_id\": \"4ccf0b65-fb99-40da-92d6-3f98730df8b2\",\n      \"location_ids\": [\n        \"a13ddb59-3e5c-4bdd-8673-fc913b93b9db\"\n      ],\n      \"first_name\": \"Jane\",\n      \"last_name\": \"Smith\"\n    }\n  ],\n  \"location_mode\": \"add\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.xenia.team/api/v1/mgt/users/provision")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-client-key"] = '<api-key>'
request["x-client-secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"users\": [\n    {\n      \"email\": \"jane.smith@example.com\",\n      \"role_id\": \"4ccf0b65-fb99-40da-92d6-3f98730df8b2\",\n      \"location_ids\": [\n        \"a13ddb59-3e5c-4bdd-8673-fc913b93b9db\"\n      ],\n      \"first_name\": \"Jane\",\n      \"last_name\": \"Smith\"\n    }\n  ],\n  \"location_mode\": \"add\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": true,
  "results": [
    {
      "email": "jane.smith@example.com",
      "status": "ok",
      "user_id": "9c1e2f3a-1111-4b2c-8d3e-4f5a6b7c8d9e"
    }
  ],
  "errors": [
    {
      "email": "dupe@example.com",
      "error": "Duplicate email in batch"
    }
  ]
}

Users

Provision Users

Batch-creates or syncs users. New users are created with the given role and locations. Existing users (matched by email, case-insensitive) have their role corrected if it differs and locations updated per location_mode; re-provisioning does not change an existing membership’s status (a Pending/Deactivated user stays that way). Validation runs for the whole batch before any row is written; a bad role_id or location_id fails only that row, reported in errors. An email that appears more than once in the same batch fails every row that shares it, not just the extras.

POST

api

mgt

users

provision

Provision Users

curl --request POST \
  --url https://api.xenia.team/api/v1/mgt/users/provision \
  --header 'Content-Type: application/json' \
  --header 'x-client-key: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data '
{
  "users": [
    {
      "email": "jane.smith@example.com",
      "role_id": "4ccf0b65-fb99-40da-92d6-3f98730df8b2",
      "location_ids": [
        "a13ddb59-3e5c-4bdd-8673-fc913b93b9db"
      ],
      "first_name": "Jane",
      "last_name": "Smith"
    }
  ],
  "location_mode": "add"
}
'

import requests

url = "https://api.xenia.team/api/v1/mgt/users/provision"

payload = {
    "users": [
        {
            "email": "jane.smith@example.com",
            "role_id": "4ccf0b65-fb99-40da-92d6-3f98730df8b2",
            "location_ids": ["a13ddb59-3e5c-4bdd-8673-fc913b93b9db"],
            "first_name": "Jane",
            "last_name": "Smith"
        }
    ],
    "location_mode": "add"
}
headers = {
    "x-client-key": "<api-key>",
    "x-client-secret": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-client-key': '<api-key>',
    'x-client-secret': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    users: [
      {
        email: 'jane.smith@example.com',
        role_id: '4ccf0b65-fb99-40da-92d6-3f98730df8b2',
        location_ids: ['a13ddb59-3e5c-4bdd-8673-fc913b93b9db'],
        first_name: 'Jane',
        last_name: 'Smith'
      }
    ],
    location_mode: 'add'
  })
};

fetch('https://api.xenia.team/api/v1/mgt/users/provision', 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://api.xenia.team/api/v1/mgt/users/provision",
  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([
    'users' => [
        [
                'email' => 'jane.smith@example.com',
                'role_id' => '4ccf0b65-fb99-40da-92d6-3f98730df8b2',
                'location_ids' => [
                                'a13ddb59-3e5c-4bdd-8673-fc913b93b9db'
                ],
                'first_name' => 'Jane',
                'last_name' => 'Smith'
        ]
    ],
    'location_mode' => 'add'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-client-key: <api-key>",
    "x-client-secret: <api-key>"
  ],
]);

$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://api.xenia.team/api/v1/mgt/users/provision"

	payload := strings.NewReader("{\n  \"users\": [\n    {\n      \"email\": \"jane.smith@example.com\",\n      \"role_id\": \"4ccf0b65-fb99-40da-92d6-3f98730df8b2\",\n      \"location_ids\": [\n        \"a13ddb59-3e5c-4bdd-8673-fc913b93b9db\"\n      ],\n      \"first_name\": \"Jane\",\n      \"last_name\": \"Smith\"\n    }\n  ],\n  \"location_mode\": \"add\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-client-key", "<api-key>")
	req.Header.Add("x-client-secret", "<api-key>")
	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://api.xenia.team/api/v1/mgt/users/provision")
  .header("x-client-key", "<api-key>")
  .header("x-client-secret", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"users\": [\n    {\n      \"email\": \"jane.smith@example.com\",\n      \"role_id\": \"4ccf0b65-fb99-40da-92d6-3f98730df8b2\",\n      \"location_ids\": [\n        \"a13ddb59-3e5c-4bdd-8673-fc913b93b9db\"\n      ],\n      \"first_name\": \"Jane\",\n      \"last_name\": \"Smith\"\n    }\n  ],\n  \"location_mode\": \"add\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.xenia.team/api/v1/mgt/users/provision")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-client-key"] = '<api-key>'
request["x-client-secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"users\": [\n    {\n      \"email\": \"jane.smith@example.com\",\n      \"role_id\": \"4ccf0b65-fb99-40da-92d6-3f98730df8b2\",\n      \"location_ids\": [\n        \"a13ddb59-3e5c-4bdd-8673-fc913b93b9db\"\n      ],\n      \"first_name\": \"Jane\",\n      \"last_name\": \"Smith\"\n    }\n  ],\n  \"location_mode\": \"add\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": true,
  "results": [
    {
      "email": "jane.smith@example.com",
      "status": "ok",
      "user_id": "9c1e2f3a-1111-4b2c-8d3e-4f5a6b7c8d9e"
    }
  ],
  "errors": [
    {
      "email": "dupe@example.com",
      "error": "Duplicate email in batch"
    }
  ]
}

This endpoint has no hasPermission/hasFeature gate of its own — any valid client key can provision users into its own workspace. Pre-provisioning a user here with a role and locations before their first SSO login means they land in that role and those locations instead of the workspace’s bare default SSO role. See the Single Sign-On guide.

Need role_id/location_ids values? See Get Roles and Get Locations.

This endpoint returns a custom envelope — { status, results, errors } — not the { data, extra_meta } shape used by other user-management endpoints. A 200 response does not mean every row succeeded: always check errors. A duplicated email within the same batch fails every row that shares it, not just the extra ones.

Re-provisioning an existing user corrects their role and locations, but does not change their membership status — a Pending or Deactivated user stays that way. It also doesn’t bypass your workspace’s user-seat limit: if provisioning a new user would exceed it, that row fails in errors.

Authorizations

x-client-key

string

header

required

Client API key for authentication

x-client-secret

string

header

required

Client secret for authentication

Body

application/json

users

object[]

required

Minimum array length: 1

Show child attributes

location_mode

enum<string>

default:add

add (default) only adds missing location memberships, never removes. replace makes the user's locations exactly match location_ids, removing any not listed.

Available options:

add,

replace

Response

Batch processed. Per-row outcomes are in results/errors — HTTP 200 does not mean every row succeeded, check errors.

status

boolean

results

object[]

Show child attributes

errors

object[]

Show child attributes

⌘I

Authentication

Users

Locations

Enterprise Locations

Roles

Teams

Tasks

Projects

Reporting

Provision Users

Authorizations

Body

Response