Users

Caution

User management endpoints require the users:read, users:create, users:update, or users:delete permissions respectively.

Overview

Manage users within your organization. Users are assigned roles that control their access to features through granular permissions.

Users can be either native (created in the organization) or members (added from another organization). The is_member field in responses indicates cross-org members, who have limited update/delete behavior.

Profile & Password Change

All users (regardless of role) can access their profile to view account information and change their password. The Profile page is accessible from the user menu in the top navigation.

Get Current User

GET /api/me

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "full_name": "John Doe",
    "role": {
      "id": "uuid",
      "name": "admin",
      "description": "Full access to all features"
    },
    "permissions": ["users:read", "users:create", "contacts:read", "..."],
    "is_super_admin": false,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Change Password

PUT /api/me/password

Request Body

{
  "current_password": "oldpassword",
  "new_password": "newsecurepassword"
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | current_password | string | Yes | Current password for verification | | new_password | string | Yes | New password (minimum 8 characters) |

Response

{
  "status": "success",
  "data": {
    "message": "Password changed successfully"
  }
}

List Users

Retrieve all users in your organization.

GET /api/users

Note

Requires users:read permission.

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | search | string | Filter by name or email |

Response

{
  "status": "success",
  "data": {
    "users": [
      {
        "id": "uuid",
        "email": "user@example.com",
        "full_name": "John Doe",
        "role_id": "uuid",
        "role": {
          "id": "uuid",
          "name": "agent",
          "is_system": true
        },
        "is_active": true,
        "is_available": true,
        "is_member": false,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Tip

The is_member field is true for users who belong to another organization but have been added as members to the current organization.

Get User

Retrieve a single user.

GET /api/users/{id}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "full_name": "John Doe",
    "role_id": "uuid",
    "role": {
      "id": "uuid",
      "name": "agent",
      "is_system": true
    },
    "is_active": true,
    "is_available": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Create User

Create a new user in your organization.

POST /api/users

Note

Requires users:create permission.

Request Body

{
  "email": "newuser@example.com",
  "password": "securepassword",
  "full_name": "Jane Smith",
  "role_id": "uuid"
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | email | string | Yes | Unique email address | | password | string | Yes | Minimum 8 characters | | full_name | string | Yes | Display name | | role_id | string | No | UUID of the role to assign. If not provided, uses the organization's default role |

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "email": "newuser@example.com",
    "full_name": "Jane Smith",
    "role_id": "uuid",
    "role": {
      "id": "uuid",
      "name": "agent",
      "is_system": true
    },
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Update User

Update user details or role.

PUT /api/users/{id}

Note

Requires users:update permission.

Request Body

{
  "full_name": "Jane Doe",
  "role_id": "uuid",
  "is_active": true
}

| Field | Type | Description | |-------|------|-------------| | email | string | New email address | | password | string | New password (min 8 chars) | | full_name | string | Display name | | role_id | string | UUID of the role to assign | | is_active | boolean | Enable/disable user |

Caution

You cannot demote yourself or change your own role.

Note

For cross-org members (is_member: true), only role_id can be updated. The role is changed in the user_organizations table, not the user's account. Other fields like email, password, full_name, and is_active cannot be modified for members.

Delete User

Remove a user from the organization.

DELETE /api/users/{id}

Note

Requires users:delete permission.

Caution

• You cannot delete yourself
• You cannot delete the last admin user
• Deleting a native user will remove their account and unassign all their contacts
• Deleting a cross-org member only removes them from the current organization — their account remains intact in their home organization

Response

{
  "status": "success",
  "data": {
    "message": "User deleted successfully"
  }
}

User Availability

Users can set their availability status for chat routing.

Update Availability

PUT /api/users/{id}/availability

Request Body

{
  "is_available": true
}

List My Organizations

Retrieve all organizations the current user belongs to. Used by the organization switcher.

GET /api/me/organizations

Response

{
  "status": "success",
  "data": {
    "organizations": [
      {
        "organization_id": "uuid",
        "name": "Acme Corp",
        "slug": "acme-corp-a1b2c3d4",
        "role_name": "admin",
        "role_id": "uuid",
        "is_default": true
      },
      {
        "organization_id": "uuid",
        "name": "Partner Org",
        "slug": "partner-org-e5f6g7h8",
        "role_name": "agent",
        "role_id": "uuid",
        "is_default": false
      }
    ]
  }
}

See Also

• Roles & Permissions - Learn about the permission system
• Roles API - Manage roles programmatically