> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# User Lifecycle

> Manage users from invitation to removal

## 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`

```bash theme={null}
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:**

```json theme={null}
{
  "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

| 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`

```bash theme={null}
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:**

| 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:**

```json theme={null}
{
  "status": true,
  "statusCode": 201,
  "message": "User created successfully",
  "data": {
    "id": "new-user-uuid",
    "firstName": "Jane",
    "lastName": "Smith",
    "emailId": "jane.smith@example.com",
    "status": "Pending"
  }
}
```

<Note>
  The user will receive an invitation email with a link to set their password and complete registration.
</Note>

***

## Get User Context

Retrieve information about the currently authenticated API user.

**Endpoint:** `GET /api/v1/mgt/user-context`

```bash theme={null}
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:**

```json theme={null}
{
  "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`

```bash theme={null}
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`

```bash theme={null}
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"
  }'
```

<Warning>
  Changing a user's role takes effect immediately. The user will gain or lose permissions based on the new role.
</Warning>

***

## 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`

```bash theme={null}
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!"
  }'
```

<Note>
  Password must meet security requirements: minimum 8 characters, at least one uppercase letter, one lowercase letter, and one number.
</Note>

***

## 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`

```bash theme={null}
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`

```bash theme={null}
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:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "message": "User deactivated successfully"
}
```

<Tip>
  Deactivated users can be reactivated later. Use this for temporary suspensions or employees on leave.
</Tip>

***

## Reactivate User

Restore access for a previously deactivated user.

**Endpoint:** `PATCH /api/v1/mgt/users/{userId}/status/Active`

```bash theme={null}
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}`

```bash theme={null}
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:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "message": "User removed successfully"
}
```

<Warning>
  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.
</Warning>

***

## Resend Invitation

Resend the invitation email to a pending user.

**Endpoint:** `GET /api/v1/mgt/workspaces/{workspaceId}/users/{userId}/resend-invite`

```bash theme={null}
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

```bash theme={null}
# 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)

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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`         |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Role Management" icon="shield" href="/guides/workflows/role-management">
    Create and manage custom roles
  </Card>

  <Card title="Team Management" icon="users" href="/guides/workflows/team-management">
    Organize users into teams
  </Card>
</CardGroup>