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 (case-insensitive)
role_id	string	Filter by role UUID
online_only	boolean	Filter to return only online users (true/false)
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 50)

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,
          "permissions": [
            {
              "id": "uuid",
              "resource": "messages",
              "action": "create",
              "description": "Send messages"
            }
          ]
        },
        "is_active": true,
        "is_available": true,
        "is_super_admin": false,
        "is_member": false,
        "organization_id": "uuid",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50,
    "online_count": 1
  }
}

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,
    "is_super_admin": false,
    "is_member": false,
    "organization_id": "uuid",
    "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 12 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,
    "is_available": true,
    "is_super_admin": false,
    "is_member": false,
    "organization_id": "uuid",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_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 12 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/me/availability

Request Body

{
  "is_available": true
}

Response

{
  "status": "success",
  "data": {
    "message": "Availability updated successfully",
    "is_available": true,
    "status": "available",
    "break_started_at": null,
    "transfers_to_queue": 0
  }
}

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