Authentication
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.
- Name – so you recognise it later ("Home Assistant", "Claude").
- 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.
- Permissions (scopes) – grant only what the integration needs.
- 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#
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.
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.