Tokens, capabilities, and scope
The two-axis security model: read/write and whole-library/specific-folders.
Every Graniite token carries two orthogonal axes: what it can do (capabilities) and what it can see (access scope). The combination determines which endpoints it can call and which rows those calls touch.
Capabilities
| Capability | What it unlocks |
|---|---|
read | MCP read tools (search_knowledge_base, get_item, list_recent) and all REST GET endpoints |
write | MCP add_to_knowledge and REST POST and DELETE endpoints (ingest, uploads, delete, organize) |
Every token includes read even if you only check write. It is implicit. Without read, the token could not discover its own write tools via tools/list.
Access scope
| Scope | Effect |
|---|---|
Whole library (is_unscoped: true) | Token sees every folder and every item the user owns. Can create and delete folders. |
| Specific folders (a list of folder IDs) | Token sees only the listed folders. Cannot see, read, or touch anything outside that list. |
The scope is fixed at mint time. A scoped token cannot grow its own access by creating new folders. POST /api/v1/folders returns 403 for scoped tokens. Mint a fresh whole-library token if you need folder-creation rights.
Picking a scope shape for your use case
| Use case | Scope to mint |
|---|---|
| Single-folder agent (one Claude Desktop install to one folder of notes) | Specific folders, list of one |
| Multi-folder agent (Cursor that needs both your "Code" and "Docs" folders) | Specific folders, list of two |
| n8n automation that does library-wide management | Whole library |
| Read-only viewer (mobile app, dashboard) | Whole library with read capability only |
| Time-boxed integration (Zapier free trial) | Any scope, set Auto-revoke after to 30 days |
Auto-file behavior
When you ingest content via MCP add_to_knowledge or REST POST /api/v1/ingest, the new item lands in the token's folder only when the scope is exactly one folder. Single-folder tokens auto-file. Multi-folder and whole-library tokens leave new items unfiled. Add memberships afterward via POST /api/v1/items/:id/folders.
This is called the scope-size-1 rule. It makes the common case (one token, one folder, one agent) work without extra steps, while keeping multi-scope explicit.
When folder deletion affects a token
Folders cascade through token scopes. If a token is scoped to [A, B, C] and the user deletes folder A:
- The scope automatically shrinks to
[B, C]. - Items only in A become invisible to the token but stay in the user's library.
- The token stays valid.
If a token's last scoped folder is deleted, an auto-revoke trigger kicks in. The token is set to revoked_at = now() rather than left silently returning empty results from every endpoint.
Where to mint a token
Tokens are created at https://graniite.co/settings/integrations. The Mint dialog uses an Airtable-style picker:
- Capabilities: check
writeif the integration needs to add or modify content. - Access: choose "Whole library" or "Specific folders". "Specific folders" opens a multi-select picker.
- KB items only: when checked, list and get exclude items the user flagged as not-in-KB. Recommended for agents.
- Auto-revoke after: defaults to 1 year. Shorter windows reduce the blast radius of a leak.
The raw token string is shown once. Save it somewhere safe. If you lose it, revoke and recreate.