# Users

> User management API

Source: https://docs.soosh.io/reference/api/users/

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

```json
{
  "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

```json
{
  "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

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

### Update Settings

Update the current user's notification preferences.

`PUT /api/me/settings`

#### Request Body

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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 |

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

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

```json
{
  "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

```json
{
  "is_available": true
}
```

## List My Organizations

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

`GET /api/me/organizations`

### Response

```json
{
  "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](https://docs.soosh.io/features/roles-permissions) - Learn about the permission system
- [Roles API](https://docs.soosh.io/reference/api/roles) - Manage roles programmatically