Scopes

A scope is a single permission on an API key, named resource:action. A key holds a set of them, and a tool refuses to run unless the key holds every scope that tool declares. This page lists all of them, which tools need each one, and the presets you can start from.

The scope table

Fourteen standard scopes, plus one reserved for Monofile administrators.

Scope	What it allows	Tools that require it
`files:read`	Reading and inspecting files, and reading version history	`read`, `canvas_check`, `list_versions`, `read_version`, `list_changesets`
`files:write`	Creating and changing files, and restoring old content	`write`, `edit`, `create_diagram`, `create_canvas`, `canvas_edit`, `revert_file`, `checkpoint`, `revert_changeset`
`files:delete`	Removing files and folders	`revert_changeset` (a revert deletes files the changeset created)
`shares:read`	Checking what is shared	`get_folder_share_status`, `get_share_link`
`shares:write`	Publishing and revoking shares	`share_folder`, `unshare_folder`, `create_share_link`, `revoke_share_link`
`community:read`	Browsing and reading public folders	`list_community_folders`, `public_bash`
`community:write`	Copying public work into your workspace	`fork_folder`
`users:read`	Reading profiles and the user directory	`get_my_profile`, `get_user`, `list_users`
`users:write`	Changing your own profile	`update_profile`
`social:read`	Reading comments, followers and the feed	`list_comments`, `get_followers`, `get_following`, `get_feed`
`social:write`	Voting, commenting and following	`vote_folder`, `vote_comment`, `add_comment`, `edit_comment`, `delete_comment`, `follow_user`, `unfollow_user`
`search:semantic`	Meaning-based search over your own files	`semantic_search`
`embeds:read`	Reading embed configuration	None currently on the API
`embeds:write`	Managing embed configuration	None currently on the API
`docs:admin`	Administering Monofile's own public documentation	None. Excluded from every preset, and only effective for a key whose owner is a Monofile administrator.

Two tools declare no scope at all:

get_key_info needs none, so any valid key can ask what it is allowed to do.
bash declares none because the check depends on the command. The built-in shell derives the requirement from the command text (files:read to list and read, files:write for mkdir, mv, cp, touch and redirects, files:delete for rm). The full shell ignores the command text and checks what the command changed: creating, editing or renaming needs files:write, deleting needs files:delete. A missing scope rejects the whole set of changes and writes nothing, so a script, an alias or a python -c cannot smuggle a write past the check.

You can grant embeds:read and embeds:write, but no tool requires them today, so granting them changes nothing.

Presets

Preset	Scopes	Good for
Read Only	`files:read`	Browsing, auditing, search over a workspace you should not change
Read and Write	`files:read`, `files:write`	Ordinary development: read, create, edit
Full Access	Every standard scope	Automation that also shares, comments and forks

Full Access means the fourteen standard scopes. No preset includes docs:admin, and no default grants it.

Choosing scopes

Start read-only and widen when a call fails. INSUFFICIENT_SCOPE names the missing scope:

json

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Missing required scopes: files:delete"
  }
}

Four rules:

Write and delete are separate. A key with files:write can overwrite a file but cannot rm it. Use that split for an agent that edits files.
Reverting needs both. revert_changeset requires files:write and files:delete, because undoing a run means deleting the files that run created.
Social write is loud. social:write lets a key vote, comment and follow under your name, in public. Grant it only to something you want speaking for you.
Scopes are not folder scope. Scopes say which operations the key may perform; folder scope says where. A narrow scope set on a folder-scoped key is the tightest useful configuration; see Authentication.

To see what a key holds, call get_key_info:

POST/api/tools/get_key_info

{}

To see which scopes each live tool declares, call GET /api/tools with that key. Every entry carries its own requiredScopes.

GET/api/tools

Next steps

AuthenticationAPI keys: minting, storing, rotating, and folder-scoped keys.
Calling ToolsThe one-endpoint pattern, the MCP-shaped envelope, and the index of every tool.
Errors and LimitsEvery error code, what causes it, and how to recover.
File and Shell ToolsReading, writing and editing files, plus the two shell tiers.