Skip to main content

​
Overview

This guide covers the complete user lifecycle in Xenia: inviting users, creating accounts, managing profiles, changing roles, and removing users from your workspace.

​
User Lifecycle Flow

1. Invite User    → Send invitation email
2. User Accepts   → Creates account / joins workspace
3. Manage User    → Update profile, change role, set permissions
4. Deactivate     → Temporarily disable access
5. Remove         → Permanently remove from workspace

​
List Users

Retrieve all users in your workspace with optional filtering. 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" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
Response: 
{
  "status": true,
  "statusCode": 200,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "emailId": "john.doe@example.com",
      "status": "Active",
      "phoneNo": "+1234567890",
      "timezone": "America/New_York",
      "createdAt": "2024-01-15T10:30:00Z",
      "role": {
        "id": "role-uuid",
        "title": "Full User"
      },
      "locations": [
        {
          "locationId": "location-uuid"
        }
      ]
    }
  ]
}

​
User Statuses

StatusDescription
ActiveUser has full access to the workspace
PendingUser has been invited but hasn’t accepted
InactiveUser account is deactivated

​
Create User

Add a new user to your workspace. The user will receive an invitation email. Endpoint: POST /api/v1/mgt/workspaces/{workspaceId}/users 
curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/users" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "emailId": "jane.smith@example.com",
    "phoneNo": "+1234567890",
    "roleId": "role-uuid",
    "locationIds": ["location-uuid-1", "location-uuid-2"]
  }'
Request Body:
FieldTypeRequiredDescription
firstNamestringYesUser’s first name
lastNamestringYesUser’s last name
emailIdstringYesUser’s email address (must be unique)
phoneNostringNoUser’s phone number
roleIdstringNoRole to assign (defaults to Basic User)
locationIdsarrayNoLocations to assign user to
Response: 
{
  "status": true,
  "statusCode": 201,
  "message": "User created successfully",
  "data": {
    "id": "new-user-uuid",
    "firstName": "Jane",
    "lastName": "Smith",
    "emailId": "jane.smith@example.com",
    "status": "Pending"
  }
}
The user will receive an invitation email with a link to set their password and complete registration.

​
Get User Context

Retrieve information about the currently authenticated API 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: 
{
  "status": true,
  "data": {
    "user": {
      "id": "user-uuid",
      "firstName": "API",
      "lastName": "User",
      "emailId": "api@example.com"
    },
    "workspaces": [
      {
        "id": "workspace-uuid",
        "name": "My Workspace",
        "role": "Admin"
      }
    ]
  }
}

​
Update User Profile

Modify a user’s profile information. 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 "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "phoneNo": "+1987654321",
    "timezone": "America/Los_Angeles"
  }'
Request Body:
FieldTypeDescription
firstNamestringUpdated first name
lastNamestringUpdated last name
phoneNostringUpdated phone number
timezonestringUser’s timezone (IANA format)

​
Change User Role

Update the role assigned to a user. Endpoint: PATCH /api/v1/mgt/workspaces/{workspaceId}/users/{userId}/role 
curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/users/{userId}/role" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "roleId": "new-role-uuid"
  }'
Changing a user’s role takes effect immediately. The user will gain or lose permissions based on the new role.

​
Set User Password

Set or reset a user’s password. This is typically used during initial setup or password reset flows. Endpoint: POST /api/v1/mgt/users/{userId}/set-password 
curl -X POST "https://api.xenia.team/api/v1/mgt/users/{userId}/set-password" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "SecurePassword123!"
  }'
Password must meet security requirements: minimum 8 characters, at least one uppercase letter, one lowercase letter, and one number.

​
Set User Login PIN

Configure a 4-digit PIN for quick login (mobile app feature). Endpoint: POST /api/v1/mgt/users/{userId}/set-login-pin 
curl -X POST "https://api.xenia.team/api/v1/mgt/users/{userId}/set-login-pin" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "pin": "1234"
  }'

​
Deactivate User

Temporarily disable a user’s access without removing them from the workspace. 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" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
Response: 
{
  "status": true,
  "statusCode": 200,
  "message": "User deactivated successfully"
}
Deactivated users can be reactivated later. Use this for temporary suspensions or employees on leave.

​
Reactivate User

Restore access for a previously deactivated user. Endpoint: PATCH /api/v1/mgt/users/{userId}/status/Active 
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" \
  -H "workspace-id: YOUR_WORKSPACE_ID"

​
Delete User

Permanently remove a user from the workspace. Endpoint: DELETE /api/v1/mgt/workspaces/{workspaceId}/users/{userId} 
curl -X DELETE "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/users/{userId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
Response: 
{
  "status": true,
  "statusCode": 200,
  "message": "User removed successfully"
}
This action is permanent. The user will lose all access and their assignments (tasks, locations) will be unassigned. Consider deactivating instead if the removal is temporary.

​
Resend Invitation

Resend the invitation email to a pending user. Endpoint: GET /api/v1/mgt/workspaces/{workspaceId}/users/{userId}/resend-invite 
curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/users/{userId}/resend-invite" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID"

​
Complete User Lifecycle Example

Here’s a complete workflow for onboarding a new employee:

​
Step 1: Create the User

# Create user with role and location assignment
curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/users" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "New",
    "lastName": "Employee",
    "emailId": "new.employee@company.com",
    "roleId": "full-user-role-uuid",
    "locationIds": ["store-123-uuid"]
  }'

​
Step 2: User Accepts Invitation

(User clicks link in email and sets password)

​
Step 3: Promote to Admin (if needed)

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

​
Step 4: Employee Leaves - 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" \
  -H "workspace-id: YOUR_WORKSPACE_ID"

​
Step 5: After Transition Period - Remove

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

​
Permissions Required

ActionPermission Required
List usersAuthenticated
Create userCAN_MANAGE_USERS
Update user profileCAN_MANAGE_USERS or self
Change user roleCAN_MANAGE_USERS
Deactivate userCAN_MANAGE_USERS
Delete userCAN_MANAGE_USERS

​
Next Steps

Role Management

Create and manage custom roles

Team Management

Organize users into teams