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. 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"
  }'

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)

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

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)

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)

​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)

Update User Profile

Change User Role

Deactivate User

Set User Status

Set User Password

Set User Login PIN

Delete User

Permissions Required

Next Steps