Authentication
Authenticate API and MCP requests with workspace API keys.
All programmatic access to Snoze authenticates with an API key scoped to a workspace.
Creating a key
Create and manage keys in Workspace settings → API keys. Each key has:
- a workspace it belongs to — the key itself pins which workspace flat routes like
/v1/itemsoperate on, - a set of scopes limiting what it can read and write,
- an optional expiry.
Treat keys like passwords: store them in a secret manager, never commit them, and rotate them if exposed.
Using a key
Pass the key as a bearer token:
curl https://api.snoze.dev/v1/items \
-H "Authorization: Bearer $SNOZE_API_KEY"Scopes
Keys are least-privilege by default: grant only the scopes an integration needs. A request beyond a key's scopes fails with 403 forbidden; items a key can't see are filtered out of listings and read as 404. A key can also never exceed what its workspace membership allows — scopes narrow access, they don't add it.
The catalog, grouped by what most integrations need first:
| Scope | Grants |
|---|---|
resources:read / resources:write | List, read, create, move, and delete sidebar items (/v1/items). |
databases:read / databases:write | Read and change database schemas. |
records:read / records:write / records:comment | Read, write, and comment on database records. |
files:read / files:write | Download descriptors and uploads (/v1/files). |
surfaces:read / surfaces:write | Page, note, dashboard, canvas, and form surfaces. |
blocks:read / blocks:write / blocks:comment | Page block content (used by MCP page editing). |
views:read / views:write | Saved database views — the query layer for records. |
canvas:read / canvas:write | Canvas elements. |
actions:read / actions:write / actions:run | Workspace actions, including running them. |
automations:read / automations:write | Automation graphs and runs. |
webhooks:read / webhooks:write | Outbound and inbound webhook endpoints. |
data_sources:read / data_sources:write | External data source syncs. |
integrations:read / integrations:write | Connected apps. |
ai:read / ai:write | Assistant and AI-database features. |
time_entries:read / time_entries:write / time_entries:manage | Time tracking. |
workspace:read / workspace:update / workspace:delete | Workspace metadata. |
members:read / members:invite / members:manage | Membership. |
api_keys:read / api_keys:write | Managing keys themselves. |
billing:read / billing:manage | Plan and billing state. |
A minimal read-only reporting key is resources:read + databases:read + records:read; a typical two-way integration adds the matching :write scopes and files:write.