> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Users API

> List and invite users for tenant user management.

The Users API allows tenant administrators to list existing users and invite new ones. User creation uses a privacy-safe response that does not reveal whether an email is already registered.

## Base path

```
/api/v1/users
```

***

## List users

```
GET /api/v1/users
```

Returns a paginated list of users for the current tenant, ordered by creation date (newest first). Only returns non-sensitive fields.

### Query parameters

| Parameter | Required | Type    | Description                             |
| --------- | -------- | ------- | --------------------------------------- |
| `limit`   | No       | integer | Maximum results per page. Default `25`. |
| `cursor`  | No       | string  | Cursor for keyset pagination.           |

### Response `200`

```json theme={null}
{
  "data": [
    {
      "id": "usr_001",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "image": null,
      "role": "admin",
      "lastLoginAt": "2026-03-16T10:00:00.000Z",
      "createdAt": "2026-02-01T12:00:00.000Z",
      "updatedAt": "2026-03-16T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 25,
    "hasMore": false,
    "nextCursor": null
  }
}
```

***

## Invite a user

```
POST /api/v1/users
```

Creates a new user account for the tenant. If the email is already registered, the response is identical to a successful creation to prevent email enumeration.

### Request body

| Field   | Required | Type           | Description                            |
| ------- | -------- | -------------- | -------------------------------------- |
| `email` | **Yes**  | string         | Valid email address.                   |
| `name`  | No       | string \| null | User display name.                     |
| `role`  | No       | enum           | `viewer` (default), `editor`, `admin`. |

### Example request

```json theme={null}
{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "editor"
}
```

### Response `201`

```json theme={null}
{
  "message": "If this email is not already registered, an account has been created."
}
```

<Note>
  The response message is intentionally vague for security. The same `201` status and message is returned regardless of whether the user already existed.
</Note>

### Error codes

| Code  | Reason                                          |
| ----- | ----------------------------------------------- |
| `400` | Validation error (invalid email, invalid role). |
| `415` | `Content-Type` is not `application/json`.       |

***

## Update a user

```
PUT /api/v1/users/{id}
```

Updates an existing user's name or role.

### Path parameters

| Parameter | Required | Type   | Description |
| --------- | -------- | ------ | ----------- |
| `id`      | **Yes**  | string | User ID.    |

### Request body

All fields are optional. Only include the fields you want to change.

| Field  | Type           | Description                                |
| ------ | -------------- | ------------------------------------------ |
| `name` | string \| null | Updated display name.                      |
| `role` | enum           | Updated role: `viewer`, `editor`, `admin`. |

### Example request

```json theme={null}
{
  "name": "Jane Doe",
  "role": "admin"
}
```

### Response `200`

Returns the full updated user object.

```json theme={null}
{
  "id": "usr_001",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "image": null,
  "role": "admin",
  "lastLoginAt": "2026-03-16T10:00:00.000Z",
  "createdAt": "2026-02-01T12:00:00.000Z",
  "updatedAt": "2026-03-30T14:00:00.000Z"
}
```

***

## Delete a user

```
DELETE /api/v1/users/{id}
```

Permanently deletes a user from the tenant.

### Path parameters

| Parameter | Required | Type   | Description |
| --------- | -------- | ------ | ----------- |
| `id`      | **Yes**  | string | User ID.    |

### Response `204`

No content. The user has been deleted.

### Error codes

| Code  | Reason                                |
| ----- | ------------------------------------- |
| `404` | User not found in the current tenant. |

***

## Role requirements

| Method | Minimum role |
| ------ | ------------ |
| GET    | `admin`      |
| POST   | `admin`      |
| PUT    | `admin`      |
| DELETE | `admin`      |