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

# Authentication

> API key authentication, access roles, and device scoping.

## API Key

All endpoints require authentication via the `X-API-Key` header, except `GET /health`.

```bash theme={null}
curl -H "X-API-Key: YOUR_API_KEY" https://your-api-host/devices
```

## Roles

| Role      | Access                                                                                       |
| --------- | -------------------------------------------------------------------------------------------- |
| **User**  | Devices, telemetry, commands, lock events, trips, and WebSocket — scoped to assigned devices |
| **Admin** | Everything above (unrestricted) plus device management, configuration, and user management   |

## Device Scoping

Non-admin users are restricted to specific devices using the `allowed_hardware_ids` field on their user record. This scoping applies to:

* **REST API** — all `/devices/:id/*` routes, `/lock-events`, `/trips`
* **WebSocket** — `subscribe` and `command` messages

| `allowed_hardware_ids` value               | Access                                                |
| ------------------------------------------ | ----------------------------------------------------- |
| Array of IDs (e.g. `["ABC123", "DEF456"]`) | Can access only those devices                         |
| `null` or `undefined`                      | No device access (must be explicitly set to an array) |
| *(Admin users)*                            | Unrestricted access to all devices                    |

<Warning>Users with `allowed_hardware_ids` set to `null` have **no device access**. You must explicitly set it to an array for the user to access any devices.</Warning>