# 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 |