Permissions and consent
Which permissions the tools need, how the consent page bundles them, and what to do when one is missing.
- For
- Anyone who connects an assistant or issues the key for one
- Prerequisite
- none
On this page
Every tool needs the permissions of the API operations it calls, exactly those and no others. This page lists them, shows how the consent page bundles them into areas, and explains what to do when one is missing.
What the client asks for
The server publishes the permissions its tools need in two places: under scopes_supported in the resource metadata (GET https://mcp.<domain>/.well-known/oauth-protected-resource, RFC 9728), and as scope in the WWW-Authenticate header of its 401 answer. A client passes them on unchanged into its sign-in. Without scope, the authorization server rejects the request.
All 22 permissions can be delegated and can also be carried by an API key. Every tool is therefore reachable in both ways.
The areas of the consent page
On the page Allow access? the permissions appear bundled into areas, each with one sentence and one switch. All requested areas are switched on at the start, and the person may switch individual ones off. The access token then carries only the granted permissions.
| Area | Permissions | Tools that need them |
|---|---|---|
| Scenes | scene.list, scene.read, scene.create, scene.update, scene.publish |
Every tool around scenes, from list_scenes to publish_scene |
| Playlists & schedules | playlist.list, playlist.read, playlist.create, playlist.update, schedule.list, schedule.update |
The playlist tools, list_schedules, assigning programs, and overrides |
| Media | asset.list |
list_assets |
| Displays & locations | fleet.player.list, fleet.player.read, fleet.player.update, fleet.player.command.issue, location.list, location.read, location.create, location.update |
The display, video wall, and location tools, remote commands, and screenshots |
| Manage web displays | fleet.web-display.manage |
create_web_display, issue_web_display_link, delete_web_display |
| Reports | analytics.query.run |
get_hygiene |
Four tools need no permission, only a valid credential: whoami, list_widgets, get_widget_schema, and list_graphics. The widget catalog and the graphics library are the same for every organization. Which tool needs which permission exactly is under All tools.
With an API key
A key of the class Full access carries every permission that you hold yourself and that a key can carry, and with that every tool. For less, create a key of the class Custom with the permissions of the areas you want to allow, see Create an API key. For an assistant that should only read, the class Read only is enough for every reading tool except get_hygiene, which needs analytics.query.run.
When a permission is missing
A tool without its permission answers permission_denied and names the area that the consent would have to include, in the words of the English consent page:
A consent can't be extended afterward. Revoke the connection under Settings › My account › Security and allow it again with the area switched on.
whoami tells you this before anyone tries a tool. It compares the permissions of your credential with those the tools need and names the missing ones:
If a permission is still missing after you allowed the connection again, your role doesn't include it. Delegated access never gets more than the account behind it, and only someone who assigns roles can help. With an API key, issue a new one with the permission.
{ "error": "permission_denied", "hint": "The credential lacks the permission for this action. This tool works in the area \"Displays & locations\". The consent of this connection must include it.", "correlationId": "0198f2c1-…"}{ "account": { "…": "…" }, "permissionCount": 14, "missingPermissions": ["location.create"], "hint": "These tools need a new consent: disconnect the connection in the client and connect again, new permissions only appear then. If a permission is still missing afterwards, the account itself does not carry it."}New tools, new consent
When a tool is added that needs a permission no tool needed before, the list grows, and an existing access token does not grow with it. It keeps the permissions of its consent. The tools behind the new permission answer permission_denied until you connect again, and whoami names the gap beforehand.
Was this helpful?