Users

Caution

User management endpoints require the users:read, users:write, or users:delete permission. There is no separate create/update action — creating and editing both use users:write.

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:write", "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 6 characters)

Response

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

Update Settings

Update the current user's notification preferences.

PUT /api/me/settings

Request Body

{
  "email_notifications": true,
  "new_message_alerts": true,
  "campaign_updates": false
}

Field	Type	Description
email_notifications	boolean	Receive email notifications
new_message_alerts	boolean	Alert on new inbound messages
campaign_updates	boolean	Notify on campaign status changes

Response

{
  "status": "success",
  "data": {
    "message": "Settings updated successfully",
    "settings": {
      "email_notifications": true,
      "new_message_alerts": true,
      "campaign_updates": false
    }
  }
}

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:write 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	Must be non-empty. No minimum length is enforced (unlike PUT /api/me/password, which requires 6+)
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:write 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
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 set their own availability status for chat routing. This always acts on the authenticated user — there is no per-user-ID availability route.

Update Availability

PUT /api/me/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