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

# Authentication

> Authenticate every request with a workspace API key.

Every `/v1` endpoint except `GET /v1/health` requires an API key.

## Create a key

1. Open the [Lusor app](https://app.lusor.ai) and go to **Settings → API Keys**.
2. Create a key and give it a name you will recognise later.
3. Copy the key. It starts with `lusor_` and is **shown once**. Lusor does not store it in a form it can show again.

Workspace admins and members can create and revoke keys, signed in to the Lusor app. Viewers can see the list of keys but cannot create or revoke them. An API key cannot create or revoke keys.

## Send the key

Use either header. They are equivalent:

```bash X-Api-Key theme={null}
curl https://api.lusor.ai/v1/devices \
  -H "X-Api-Key: $LUSOR_API_KEY"
```

```bash Authorization theme={null}
curl https://api.lusor.ai/v1/devices \
  -H "Authorization: Bearer $LUSOR_API_KEY"
```

## A key belongs to one workspace

Each key is bound to the workspace it was created in:

* Endpoints that take an optional `workspaceId` (query or body) use the key's workspace when you leave it out.
* Endpoints with `{workspaceId}` in the path need your workspace id. Read it from the `workspaceId` field of any agent (`GET /v1/agents`).
* A request that names any other workspace returns `404`, the same response as a resource that does not exist.

## Keep keys secret

* Call the API from your server, never from a browser or a mobile app you ship. Anyone holding the key can act on your workspace's phones.
* Store keys in a secret manager or environment variables, not in source control.
* Revoke a key in **Settings → API Keys** as soon as it is no longer needed or may have leaked.

## Errors

| Status | `error` | Meaning |
| - | - | - |
| `401` | `unauthenticated` | No key was sent. |
| `401` | `invalid_api_key` | The key is wrong, revoked, or not bound to a workspace. |
| `404` | `not_found` | The resource does not exist or belongs to another workspace. |
| `429` | `rate_limit_exceeded` | Too many requests. Wait the number of seconds in the `Retry-After` header and try again. See [Rate limits](https://docs.lusor.ai/billing/rate-limits.md). |

See [Errors](https://docs.lusor.ai/billing/errors.md) for every other error code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.