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.

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,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

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.

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 user will unassign all their contacts

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
}

See Also

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