Token scopes

Every Agent API Token has a scope that determines which MCP tools it can use. OnKey staff set it at issue; the token holder can't change it. The tools your client sees automatically reflect your token's scope.

Scope	Grants	Cannot
`read`	Query the Knowledge Base; read usage stats and recent questions; list prompt cards; check import status	Upload files; edit prompt cards; anything that writes or reaches workers
`full`	Everything `read` grants, plus file uploads, Prompt Card edits, and all worker-facing tools	Nothing — this is the maximum scope

See the Tool catalog for exactly which tools each scope unlocks.

Which scope to request

Request read unless the integration specifically needs to write. A read token is safe for an unattended assistant or automated workflow that only queries or reports — it can't modify the Knowledge Base, edit Prompt Cards, or reach workers, so a misconfigured prompt or a leaked token has a limited blast radius.

Request full when the integration's job is to push content into the KB, edit Prompt Cards, or send Alerts / Messages / Reminders / question replies. Every worker-facing send still requires a human to approve it through the stage → confirm gate — a full token does not allow unattended sends — but treat it with the care of a production write credential.

How scope is enforced

tools/list returns only the tools your scope permits — a read client never even sees add_files.
tools/call re-checks scope on every call; a read token calling a full tool gets a tool error. The call check is the real trust boundary; the list is a convenience.

Getting or changing a token

Staff issue and scope tokens from the Admin Portal — reply to your Virtual Operations Agent email to request one, or to ask for a different scope. See Authentication.