# List Users

List all users in the system (admin only).

**Endpoint**: `GET /api/auth/users`
**Auth**: Required (Admin only)

## Query Parameters

| Parameter | Type    | Required | Description                                     |
| --------- | ------- | -------- | ----------------------------------------------- |
| limit     | integer | No       | Maximum number of users to return (default: 50) |
| offset    | integer | No       | Number of users to skip (default: 0)            |
| search    | string  | No       | Search by email or username                     |

## Request Headers

| Header        | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| Authorization | string | Yes      | Bearer token (must have admin role) |

### Example Request

```http
GET /api/auth/users?limit=10&search=john
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

## Response (200 OK)

```json
{
  "users": [
    {
      "id": "uuid",
      "email": "user@example.com",
      "username": "johndoe",
      "first_name": "John",
      "last_name": "Doe",
      "role": "user",
      "theme": "tokyo-night",
      "max_devices": 10,
      "device_count": 3,
      "created_at": "2026-02-08T10:00:00Z",
      "updated_at": "2026-02-08T10:00:00Z"
    }
  ],
  "total": 25,
  "limit": 10,
  "offset": 0
}
```

### Response Fields

| Field          | Type    | Description                           |
| -------------- | ------- | ------------------------------------- |
| `id`           | string  | User ID (UUID)                        |
| `email`        | string  | Email address                         |
| `username`     | string  | Username                              |
| `first_name`   | string  | First name (optional)                 |
| `last_name`    | string  | Last name (optional)                  |
| `role`         | string  | User role (`"user"` or `"admin"`)     |
| `theme`        | string  | Theme preference (optional)           |
| `max_devices`  | integer | Maximum number of devices allowed     |
| `device_count` | integer | Current number of registered devices  |
| `created_at`   | string  | Account creation timestamp (ISO 8601) |
| `updated_at`   | string  | Last update timestamp (ISO 8601)      |
| `total`        | integer | Total number of users matching query  |
| `limit`        | integer | Limit applied to this request         |
| `offset`       | integer | Offset applied to this request        |

## Error Responses

| Code | Description                         |
| ---- | ----------------------------------- |
| 401  | Invalid or expired token            |
| 403  | User does not have admin privileges |
