# 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",
      "role": "user",
      "max_devices": 10,
      "active_devices": 3,
      "created_at": "2026-02-08T10:00:00Z"
    }
  ],
  "total": 25,
  "limit": 10,
  "offset": 0
}
```

## Error Responses

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

## Try It Out

<!-- API Explorer will be inserted here in Phase 3 -->