User Lifecycle

Overview

This guide covers the user-management endpoints reachable with a client key: listing users, reading the caller’s context, provisioning new users (with or without SSO), updating profiles, changing roles, setting passwords/PINs, activating/deactivating, and removing users.

Creating users is done through the Provision Users endpoint (POST /api/v1/mgt/users/provision) — which works whether or not the workspace uses SSO; see the Single Sign-On guide for how it interacts with SSO’s own automatic provisioning, and Directory Sync if you want Xenia to read your IdP’s directory instead of being told who to create. Provisioning is silent by default and can invite the users it creates — see Inviting the users you provision. The admin “register user” routes are not accessible via API key. Most actions here enforce the key’s default-user permissions (e.g. CAN_MANAGE_USERS, CAN_MANAGE_USER_ROLES) — the required permission is noted per section below — so choose a default user whose role grants what your integration needs. (Provisioning has no separate permission gate.)

Authentication & base URL

All requests go to https://api.xenia.team; every path starts with /api/v1. Authenticate with:

x-client-key: <your-client-key>
x-client-secret: <your-client-secret>
x-client-user: <optional-user-id>

The workspace is derived from the key. Where a path shows {workspaceId} it must be your key’s own workspace; most user routes also accept an unscoped form (e.g. /api/v1/mgt/users/{userId}/role) and resolve the workspace from the key automatically.

Response envelopes: list/read endpoints return { data, meta }; message-style endpoints return { data, extra_meta: { message } }; user-context returns { data, message, extra_meta: { token } }. There is no status/statusCode/success/requestId field. Successful POST/PATCH/PUT calls return HTTP 200.

List Users

Retrieve users in your workspace. Endpoint: GET /api/v1/mgt/workspaces/{workspaceId}/users

curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/users" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Query Parameters: none. This endpoint returns all users in the workspace; it does not support query-based paging or filtering — passing params such as offset or limit returns a 422. Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "emailId": "john.doe@example.com",
      "phoneNo": "+1234567890",
      "photo": null,
      "createdAt": "2024-01-15T10:30:00Z",
      "UserWorkspaces": [
        {
          "WorkspaceId": "workspace-uuid",
          "title": "Store Manager",
          "status": "Active",
          "isAdmin": false,
          "defaultLocationId": "location-uuid",
          "homepage": "tasks",
          "RoleId": "role-uuid",
          "Role": { "id": "role-uuid", "title": "Full User" }
        }
      ],
      "UserLocations": [{ "LocationId": "location-uuid" }],
      "UserWorkspace": {
        "WorkspaceId": "workspace-uuid",
        "status": "Active",
        "isAdmin": false,
        "RoleId": "role-uuid"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "total": 42
  }
}

UserWorkspaces holds a user’s membership per workspace (role, status, default location, admin flag); UserWorkspace (singular) is the membership for your key’s workspace; UserLocations lists assigned location IDs.

Membership statuses

Status	Description
`Active`	Full access to the workspace
`Pending`	Invited but not yet accepted
`Inactive`	Membership deactivated

Get User Context

Return the caller’s identity, workspace memberships, features, and permissions. When no x-client-user is supplied, this reflects the key’s default user. Endpoint: GET /api/v1/mgt/user-context

curl -X GET "https://api.xenia.team/api/v1/mgt/user-context" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response:

{
  "data": {
    "id": "user-uuid",
    "firstName": "API",
    "lastName": "User",
    "fullName": "API User",
    "emailId": "api@example.com",
    "phoneNo": null,
    "photo": null,
    "UserWorkspaces": [
      {
        "WorkspaceId": "workspace-uuid",
        "Workspace": { "id": "workspace-uuid", "name": "My Workspace", "subscriptionPlan": "..." },
        "Role": { "id": "role-uuid", "title": "Admin" }
      }
    ],
    "Features": ["ADVANCED_DASHBOARDS", "..."],
    "Permissions": { "workspace-uuid": ["CAN_MANAGE_USERS", "..."] },
    "streamChatKey": "...",
    "verificationToken": "..."
  },
  "message": "Login Successfully",
  "extra_meta": { "token": "..." }
}

Provision Users (create / sync)

Create new users or sync existing ones for a workspace in a single call — the API-key path for programmatic user creation. New users are created and existing ones (matched by email) have their role and location memberships updated. Endpoint: POST /api/v1/mgt/users/provision

curl -X POST "https://api.xenia.team/api/v1/mgt/users/provision" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "email": "jane.smith@example.com",
        "role_id": "role-uuid",
        "location_ids": ["location-uuid-1", "location-uuid-2"],
        "first_name": "Jane",
        "last_name": "Smith"
      }
    ],
    "location_mode": "add",
    "notification": "none"
  }'

Request Body:

Field	Type	Required	Description
`users`	array	Yes	One or more users to provision (min 1)
`users[].email`	string	Yes	Lower-cased and used to match/create
`users[].role_id`	uuid	Yes	Role to assign (validated against the workspace)
`users[].location_ids`	uuid[]	Yes	Location memberships (min 1, unique)
`users[].first_name`	string	No	Up to 100 chars
`users[].last_name`	string	No	Up to 100 chars
`location_mode`	string	No	`add` (default, additive) or `replace` (full replace of the user’s locations)
`notification`	string	No	`none` (default, silent) or `auto` (invite each newly created user, routed by email domain)

Resolve valid role_id and location_ids with the workspace-discovery reads — see the Roles API and Locations API.

Inviting the users you provision

By default this endpoint is silent — it creates accounts and sends nothing, which is what an integration syncing a system of record usually wants. Pass notification: "auto" to have Xenia invite each newly created user, choosing the email by their address’s domain:

Recipient	Account created	Email sent
Domain is a verified SSO domain for the workspace	`Active`, no password	A sign-in link through your identity provider
Any other domain	`Pending`	The standard invite, where they set their own password
Already had a Xenia account	Membership ensured if missing	None

An existing user is never emailed, whatever you pass: re-provisioning is a sync, not an onboarding event, and the alternative is re-mailing everyone each time your integration runs.

notification: "auto" requires the client key to have a default user, because both emails are sent on a named person’s behalf. Without one the whole batch is rejected before anything is written, rather than creating some users and failing to notify them. notification: "none" has no such requirement.

location_ids are expanded to their leaf locations before membership is written, so passing a district or region grants the stores beneath it. Membership is stored flat and several read paths match a location literally rather than walking the hierarchy, so a user holding only a parent node would sign in to empty Submissions and Tasks pages. Passing leaves directly is unaffected.

If you would rather Xenia read your identity provider’s directory than be told who to create, see Directory Sync — it mirrors the directory over SCIM and invites from it with rules that assign role and locations from directory attributes.

Response (this endpoint returns a per-user result list rather than the standard envelope):

{
  "status": true,
  "results": [
    { "email": "jane.smith@example.com", "status": "ok", "user_id": "new-user-uuid" }
  ],
  "errors": []
}

Per-user failures are returned in errors (e.g. { "email": "...", "error": "Invalid role_id: ..." }) without failing the whole batch.

Update User Profile

Modify a user’s profile fields. Endpoint: PATCH /api/v1/mgt/users/{userId}/profile

curl -X PATCH "https://api.xenia.team/api/v1/mgt/users/{userId}/profile" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "phoneNo": "+1987654321",
    "title": "Regional Manager"
  }'

Request Body (all optional):

Field	Type	Description
`firstName`	string	First name
`lastName`	string	Last name
`fullName`	string	Full name (split into first/last if provided)
`emailId`	string	Email address
`phoneNo`	string	Phone number
`title`	string	Job title
`photo`	string	Avatar path/URL

Response:

{
  "data": { "id": "user-uuid", "firstName": "Jane", "lastName": "Doe", "phoneNo": "+1987654321" },
  "extra_meta": { "message": "Profile Updated Successfully" }
}

Change User Role

Update the role assigned to a user. roleId goes in the body (the path ends at /role). Endpoint: PATCH /api/v1/mgt/users/{userId}/role

curl -X PATCH "https://api.xenia.team/api/v1/mgt/users/{userId}/role" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "roleId": "new-role-uuid" }'

Response:

{ "extra_meta": { "message": "User's role updated!" } }

Requires the CAN_MANAGE_USER_ROLES permission. Role changes take effect immediately.

Deactivate User

Set a user’s workspace membership to Inactive without removing them. Endpoint: PATCH /api/v1/mgt/users/{userId}/deactivate

curl -X PATCH "https://api.xenia.team/api/v1/mgt/users/{userId}/deactivate" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response:

{ "data": {}, "extra_meta": { "message": "User Deactivated successfully" } }

Requires CAN_MANAGE_USERS.

Set User Status

Explicitly set a user’s membership status. Valid values are Active and Inactive only (transitions to/from Pending are rejected). Use status/Active to reactivate a deactivated user. Endpoint: PATCH /api/v1/mgt/users/{userId}/status/{status}

# Reactivate
curl -X PATCH "https://api.xenia.team/api/v1/mgt/users/{userId}/status/Active" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response:

{
  "data": { "id": "user-uuid", "WorkspaceId": "workspace-uuid", "status": "Active" },
  "extra_meta": { "message": "Active status for user updated successfully" }
}

Set User Password

Set or reset a user’s password. The target user is identified in the body, not the path. Endpoint: PATCH /api/v1/mgt/set-password

curl -X PATCH "https://api.xenia.team/api/v1/mgt/set-password" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-uuid",
    "password": "SecurePass1"
  }'

Request Body:

Field	Type	Required	Description
`userId`	string	Yes	Target user ID
`password`	string	Yes	New password, minimum 6 characters

Response:

{ "data": {}, "extra_meta": { "message": "User password updated successfully" } }

Requires CAN_MANAGE_USERS and CAN_MANAGE_USERS_PASSWORD. Setting the password also activates the user’s membership. A workspace-scoped variant PATCH /api/v1/mgt/workspaces/{workspaceId}/set-password also exists.

Set a numeric login PIN (mobile quick-login). The target user is identified in the body. Because a PIN lets the target user sign in, this is a privileged action: the key’s user must hold CAN_MANAGE_USERS and CAN_MANAGE_USERS_PASSWORD (same as setting a password) — otherwise the call returns 403. Endpoint: PUT /api/v1/mgt/set-login-pin

curl -X PUT "https://api.xenia.team/api/v1/mgt/set-login-pin" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-uuid",
    "pin": "1234"
  }'

Request Body:

Field	Type	Required	Description
`userId`	string	Yes	Target user ID
`pin`	string	Yes	4–6 digit numeric string

Response:

{ "data": {}, "extra_meta": { "message": "PIN set successfully" } }

Delete User

Remove a user from the workspace. This soft-deletes the workspace membership (and location memberships); the underlying user account is hard-deleted only if they have no remaining workspaces. Endpoint: DELETE /api/v1/mgt/users/{userId}

curl -X DELETE "https://api.xenia.team/api/v1/mgt/users/{userId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response:

{ "data": {}, "extra_meta": { "message": "User Deleted successfully" } }

Requires CAN_MANAGE_USERS. You can’t delete your own user, can only remove peers/subordinates, and can’t remove the last active admin. Consider deactivating instead for temporary removals.

Permissions Required

Action	Permission
List users	Workspace access (authenticated)
Get user context	Authenticated
Provision users	API key + valid `role_id`/`location_ids` for the workspace
Update profile	Authenticated (self or user-management role)
Change role	`CAN_MANAGE_USER_ROLES`
Deactivate / Delete	`CAN_MANAGE_USERS`
Set status	Admin-or-self on the target user
Set password	`CAN_MANAGE_USERS` + `CAN_MANAGE_USERS_PASSWORD`
Set login PIN	`CAN_MANAGE_USERS` + `CAN_MANAGE_USERS_PASSWORD`

The admin “register user” routes (/api/v1/admin/...) are not on the API-key allow-list. Use POST /api/v1/mgt/users/provision for programmatic user creation.

Next Steps

Roles API

List workspace roles to resolve role_id

Locations API

List locations to resolve location_ids

Single Sign-On guide

How SSO login, just-in-time provisioning, and deactivation work together

Getting Started

Workflows

Integrations

Overview

Authentication & base URL

List Users

Membership statuses

Get User Context

Provision Users (create / sync)

Inviting the users you provision

Update User Profile

Change User Role

Deactivate User

Set User Status

Set User Password

Delete User

Permissions Required

Next Steps

Roles API

Locations API

Single Sign-On guide

​Overview

​Authentication & base URL

​List Users

​Membership statuses

​Get User Context

​Provision Users (create / sync)

​Inviting the users you provision

​Update User Profile

​Change User Role

​Deactivate User

​Set User Status

​Set User Password

​Set User Login PIN

​Delete User

​Permissions Required

​Next Steps

Roles API

Locations API

Single Sign-On guide

Overview

Authentication & base URL

List Users

Membership statuses

Get User Context

Provision Users (create / sync)

Inviting the users you provision

Update User Profile

Change User Role

Deactivate User

Set User Status

Set User Password

Set User Login PIN

Delete User

Permissions Required

Next Steps