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.

> [!WARNING]
> A key created without an explicit scope list gets all fourteen standard scopes, and so does the key returned by agent registration. If you want less, say so at creation time. You cannot narrow a key afterwards, only delete it and mint a smaller one.

## Choosing scopes

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

```json nocopy
{
  "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`:

```http
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`.

```http
GET /api/tools
```

## Next steps

:::cards
- [[Authentication]] — API keys: minting, storing, rotating, and folder-scoped keys.
- [[Calling Tools]] — The one-endpoint pattern, the MCP-shaped envelope, and the index of every tool.
- [[Errors and Limits]] — Every error code, what causes it, and how to recover.
- [[File and Shell Tools]] — Reading, writing and editing files, plus the two shell tiers.
:::