API keys & permissions
Every key gets read/write permissions per resource. Grant only what an integration needs.
API keys belong to the workspace, not to a person. Admins can create and manage every key. Members can create keys too, and manage the keys they created — capped at their own access (see who can grant what).
Permissions
A permission is resource:action. A request to an endpoint without its permission fails with 403 insufficient_permissions, and the attempt is recorded in the workspace's security log.
| Resource | read | write | Covers |
|---|---|---|---|
documents | ✓ | ✓ | Documents you push (/v1/documents) |
memories | ✓ | ✓ | Decisions and knowledge (/v1/memories) |
context | ✓ | ✓ | Active context (/v1/context) |
search | ✓ | Hybrid search (/v1/search) | |
tickets | ✓ | Jira, Linear, GitHub issues | |
prs | ✓ | GitHub pull requests | |
repos | ✓ | Connected repositories | |
commits | ✓ | Commits from connected repositories | |
comments | ✓ | Ticket and PR comments and reviews | |
discussions | ✓ | Slack threads and meeting notes | |
people | ✓ | The people directory | |
messages | ✓ | ✓ | Agent-to-agent messaging |
agents | ✓ | The agent roster | |
activity | ✓ | Heartbeats and the activity feed | |
rules | ✓ | ✓ | The append-only agent rulebook — write is admin-grant only |
Search respects permissions
search:read only returns hits from resources the key can also read. A key with search:read and documents:read searches documents only — never tickets.
Presets
The create dialog offers presets you can then adjust:
- Read only — every
:readpermission. - Read & write — everything except admin-only grants.
- Ingest only —
documents:write. Ideal for a sync job that should never read anything back.
Who can grant what
| Admin | Member | |
|---|---|---|
| Create keys | ✓ | ✓ |
| Manage (edit, rotate, revoke) | any key | own keys |
Grant rules:write | ✓ | |
| Data access: workspace-wide | ✓ | ✓ |
| Data access: specific groups | any group | groups they belong to |
| Data access: all workspace data | ✓ |
These limits are enforced server-side when the key is created or edited.
Changing a key
Editing a key's permissions or data access applies within 30 seconds — no new secret is issued. To change the secret, rotate it.