User Lifecycle

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

Invite User    → Send invitation email
User Accepts   → Creates account / joins workspace
Manage User    → Update profile, change role, set permissions
Deactivate     → Temporarily disable access
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": "[email protected]",
      "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

Status	Description
`Active`	User has full access to the workspace
`Pending`	User has been invited but hasn’t accepted
`Inactive`	User 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": "[email protected]",
    "phoneNo": "+1234567890",
    "roleId": "role-uuid",
    "locationIds": ["location-uuid-1", "location-uuid-2"]
  }'

Request Body:

Field	Type	Required	Description
`firstName`	string	Yes	User’s first name
`lastName`	string	Yes	User’s last name
`emailId`	string	Yes	User’s email address (must be unique)
`phoneNo`	string	No	User’s phone number
`roleId`	string	No	Role to assign (defaults to Basic User)
`locationIds`	array	No	Locations to assign user to

Response:

{
  "status": true,
  "statusCode": 201,
  "message": "User created successfully",
  "data": {
    "id": "new-user-uuid",
    "firstName": "Jane",
    "lastName": "Smith",
    "emailId": "[email protected]",
    "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": "[email protected]"
    },
    "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:

Field	Type	Description
`firstName`	string	Updated first name
`lastName`	string	Updated last name
`phoneNo`	string	Updated phone number
`timezone`	string	User’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.

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": "[email protected]",
    "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

Action	Permission Required
List users	Authenticated
Create user	`CAN_MANAGE_USERS`
Update user profile	`CAN_MANAGE_USERS` or self
Change user role	`CAN_MANAGE_USERS`
Deactivate user	`CAN_MANAGE_USERS`
Delete user	`CAN_MANAGE_USERS`

Getting Started

Workflows

Integrations

Overview

User Lifecycle Flow

List Users

User Statuses

Create User

Get User Context

Update User Profile

Change User Role

Set User Password

Deactivate User

Reactivate User

Delete User

Resend Invitation

Complete User Lifecycle Example

Step 1: Create the User

Step 2: User Accepts Invitation

Step 3: Promote to Admin (if needed)

Step 4: Employee Leaves - Deactivate

Step 5: After Transition Period - Remove

Permissions Required

Next Steps

Role Management

Team Management

Getting Started

Workflows

Integrations

​Overview

​User Lifecycle Flow

​List Users

​User Statuses

​Create User

​Get User Context

​Update User Profile

​Change User Role

​Set User Password

​Set User Login PIN

​Deactivate User

​Reactivate User

​Delete User

​Resend Invitation

​Complete User Lifecycle Example

​Step 1: Create the User

​Step 2: User Accepts Invitation

​Step 3: Promote to Admin (if needed)

​Step 4: Employee Leaves - Deactivate

​Step 5: After Transition Period - Remove

​Permissions Required

​Next Steps

Role Management

Team Management

Overview

User Lifecycle Flow

List Users

User Statuses

Create User

Get User Context

Update User Profile

Change User Role

Set User Password

Set User Login PIN

Deactivate User

Reactivate User

Delete User

Resend Invitation

Complete User Lifecycle Example

Step 1: Create the User

Step 2: User Accepts Invitation

Step 3: Promote to Admin (if needed)

Step 4: Employee Leaves - Deactivate

Step 5: After Transition Period - Remove

Permissions Required

Next Steps