# Authentication

> API keys, how to send them, scopes, expiry and revocation.

Every request carries an **API key** of the account that created it. Keys belong to a person, not to a workspace: they act with *your* rights, and only in the workspaces you picked for the key.

## Create a key

In the app: **Settings → API & MCP → Create key**.

1. **Name** – so you recognise it later ("Home Assistant", "Claude").
2. **Workspaces** – your personal space and the shared workspaces where you are **owner or admin**. Pro: 1 shared workspace, Premium: 5 – counted across all your keys.
3. **Permissions** (scopes) – grant only what the integration needs.
4. **Validity** – 30, 90 or 365 days, or no expiry.

The key (`lb_live_` followed by 40 letters and digits) is shown **once**. LifeButler stores only a hash of it; nobody can show it to you again. You can have up to 10 keys.

## Send the key

```http
GET /v1/me HTTP/1.1
Host: api.lifebutler.io
Authorization: Bearer lb_live_4fQm…
```

`X-API-Key: lb_live_…` works too, for tools that can't set an `Authorization` header. Never put a key in a URL.

`GET /v1/me` is a cheap way to check a key: it returns your plan, the key's scopes and its expiry.

## Scopes

| Scope | Allows |
|---|---|
| `calendar:read` | Read appointments |
| `calendar:write` | Create, change and delete appointments |
| `tasks:read` | Read tasks |
| `tasks:write` | Create, change, complete and delete tasks |
| `lists:read` | Read lists and their items |
| `lists:write` | Create lists; add, tick off and remove items |
| `documents:read` | Search, read and download documents |
| `documents:write` | Upload, edit, analyse and delete documents |
| `search` | Smart search across the workspace (needs AI turned on) |
| `butler` | Ask the butler (uses the workspace owner's AI credits) |

Listing workspaces and members (`GET /workspaces`, `GET /workspaces/{id}/members`, `GET /me`) works with every key. A missing scope answers `403 insufficient_scope`. Write scopes don't include read: grant both if you need both.

## Expiry and revocation

- An expired key answers `401 key_expired`. Create a new one.
- **Revoke** a key in the app (*Settings → API & MCP*, trash icon). It stops working **immediately** – there is no cache.
- A key also stops working for a workspace the moment you are no longer owner or admin there, and for shared workspaces beyond your plan if you downgrade. See [Workspaces, roles & security](/developers/access).

## Keep keys safe

- Treat a key like a password. Keep it on a server or in a secret store – not in a mobile app, a public repository or browser code that others can see.
- Use one key per integration, with the fewest scopes and workspaces it needs, so you can revoke one without breaking the others.
- Set an expiry for experiments.
- If a key may have leaked: revoke it, then create a new one.