Scopes - Wordsmith API

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
`reviews:write`	Start reviews and generate redlines. Submitting decisions is still proposed.	Create Review
`repositories:read`	Read and search repositories.	Repositories, Search
`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
`reports:read`	Read reports and their cells.	Reports
`reports:write`	Create, edit, run, export and delete reports, and change who they are shared with.	Run Report
`research:read`	Search and read case law and legislation.	Research
`playbooks:write`	Create, edit, generate and delete playbooks, and change who they are shared with.	Create Playbook
`blueprints:read`	List and read blueprints. Replaces `templates:read`.	Blueprints
`blueprints:write`	Change who a blueprint is shared with.	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
`directory:admin`	Administer the organisation: edit the company profile, invite and suspend members, assign roles, manage teams.	Organisation
`usage:read`	Read usage and value: your own, or your organisation’s if you may view company analytics.	Usage and value

Document actions such as 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 for each tool’s scope.

​Scopes available today

​New scopes in this proposal

​Defaults

​Scopes and MCP tools

Scopes available today

New scopes in this proposal

Defaults

Scopes and MCP tools