> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> The OAuth scopes that control what an app connected to Wordsmith can do, including the scopes this proposal adds.

> [!WARNING]
>
> **Proposed — not available yet.** This page describes a design under review.

An **API key** acts as the user who created it, with everything that user can do. An **OAuth token** carries scopes: the user chose them on the consent screen when they connected the app. Each endpoint and MCP tool needs one scope, and each scope only ever narrows what the user could already do in Wordsmith. A token never reaches anything its user cannot see.

A `:write` scope includes its `:read` scope. The exception is `files:write`, which lets an app upload files without reading the user's other files.

## Scopes available today

| Scope | Grants |
| - | - |
| `mcp:access` | Connect to the MCP server. Every MCP connection needs it. |
| `me:read` | The user's name and email. |
| `agents:read` | List agents. |
| `sessions:read` / `sessions:write` | Read past answers and conversations / ask agents questions. |
| `tasks:read` / `tasks:write` | Read tasks / create, update and comment on them. |
| `files:read` / `files:write` | Read and download files / upload them. |
| `playbooks:read` | List and read playbooks. |
| `templates:read` | List and read blueprints. Becomes `blueprints:read`; tokens holding it keep working. |
| `directory:read` | List people and teams. This proposal extends it to member and team details, roles and the company profile. |

## New scopes in this proposal

| Scope | Grants | Used by |
| - | - | - |
| `reviews:read` | Read reviews and their findings. | [Reviews](/api-reference/reviews/get-review) |
| `reviews:write` | Start reviews and generate redlines. Submitting decisions is still proposed. | [Create Review](/api-reference/reviews/create-review) |
| `repositories:read` | Read and search repositories. | [Repositories](/api-reference/repositories/list-repositories), [Search](/api-reference/search/search-knowledge) |
| `repositories:write` | Create, rename and delete repositories, add or remove their documents, and change who they are shared with. Adding documents also needs `files:read`. | [Add Documents](/api-reference/repositories/add-documents) |
| `reports:read` | Read reports and their cells. | [Reports](/api-reference/reports/get-report) |
| `reports:write` | Create, edit, run, export and delete reports, and change who they are shared with. | [Run Report](/api-reference/reports/run-report) |
| `research:read` | Search and read case law and legislation. | [Research](/api-reference/research/search) |
| `playbooks:write` | Create, edit, generate and delete playbooks, and change who they are shared with. | [Create Playbook](/api-reference/playbooks/create-playbook) |
| `blueprints:read` | List and read blueprints. Replaces `templates:read`. | [Blueprints](/api-reference/blueprints/list-blueprints) |
| `blueprints:write` | Change who a blueprint is shared with. | [Update Sharing](/api-reference/sharing/update-sharing) |
| `sessions:share` | Change who a session is shared with. Not grantable yet: until it ships, only API keys can change a session's sharing. `sessions:write` never grants it, so apps connected today do not gain sharing. | [Update Sharing](/api-reference/sharing/update-sharing) |
| `directory:admin` | Administer the organisation: edit the company profile, invite and suspend members, assign roles, manage teams. | [Organisation](/api-reference/organisation/get-company-profile) |
| `usage:read` | Read usage and value: your own, or your organisation's if you may view company analytics. | [Usage and value](/api-reference/usage/get-usage-summary) |

Document actions such as [Translate](/api-reference/documents/translate) need `files:write`, because they create files, and `files:read` for their inputs.

## Defaults

An app that requests no scope gets every scope except `directory:admin`. `directory:admin` only narrows what the person who approves it can already do: an organisation admin's token can administer the organisation, a team admin's only their own teams. On the MCP server, one tool uses it, `manage_organisation`, and a host has it only when it asks for it. Apps connected before a new scope existed are asked to approve it the next time the user reconnects. Until then the new endpoints and MCP tools return `403 insufficient_scope`, naming the missing scope.

## Scopes and MCP tools

The MCP server lists only the tools a token can use. A connection granted only `research:read` sees two tools, `legal_research` and `get_operation`, not twenty-six. See [MCP tools](/proposed/mcp-tools) for each tool's scope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.