> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.rydhm.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rydhm.ai/_mcp/server. # Scopes Every API key carries a list of scopes. A scope is written `:`, for example `experts:read`. Scopes are **deny by default**. A key can call a route only when the route names a scope the key holds. A route that names no scope can't be called with a key at all, whatever the key holds. You choose scopes under **Permissions** when you create or edit a key. See [Authentication](/developers/authentication). ## The rules * **Write includes read.** `experts:write` also allows everything `experts:read` allows. Nothing else is implied. * **Runtime scopes stand alone.** `chat:write`, `voice_sessions:write`, `meetings:join` and `mcp:use` are separate switches. In particular, `meetings:write` never grants `meetings:join`: sending an expert into a call costs money and puts it in front of people outside your workspace. * **MCP needs two scopes per tool.** `mcp:use` opens the MCP endpoint. Each MCP tool also needs its own scope (`chat:write`, `knowledge:read` or `conversations:read`). A tool the key can't use isn't listed. See [MCP](/developers/mcp). * **Expert limits apply on top.** A key limited to some experts is refused for every other expert, whatever its scopes. See [Expert-restricted keys](/developers/authentication#expert-restricted-keys). When a key lacks a scope, the API answers `403` with `error: "insufficient_scope"` and names what is missing: ```json { "statusCode": 403, "error": "insufficient_scope", "message": "This API key needs the experts:write scope.", "requiredScopes": ["experts:write"], "missingScopes": ["experts:write"], "requestId": "req_01M726GS84892WE68HMF286YFH" } ``` ## Resource scopes In the app these rows offer **None**, **Read** or **Write**. | Permission | Scope | What it allows | | ------------- | --------------------- | -------------------------------------------------------------------------------------------- | | Experts | `experts:read` | List and get experts, and read their version history. | | | `experts:write` | Create, edit and publish experts, save their MCP servers and specialists, restore a version. | | Knowledge | `knowledge:read` | List and search an expert's documents, shared collections and website imports. | | | `knowledge:write` | Add and remove documents, FAQs and website imports; manage collections. | | Tools | `tools:read` | List workspace tools and their recent calls. | | | `tools:write` | Create, edit, test and delete tools, and give them to experts. | | Conversations | `conversations:read` | List chats and read their messages. | | | `conversations:write` | Delete a conversation, and undo the delete. | | Meetings | `meetings:read` | Read meetings, transcripts, summaries and the meeting brief PDF. | | | `meetings:write` | Cancel a meeting, take the expert out, delete a meeting, regenerate a summary. | | Analytics | `analytics:read` | Read usage, outcomes, latency and what is live now, and export analyses as CSV. | ## Runtime scopes In the app these rows are a single on/off switch. | Permission | Scope | What it allows | | ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------- | | Chat | `chat:write` | Start a chat with an expert, send it messages and stream its replies. Each reply is a model call. | | Voice sessions | `voice_sessions:write` | Mint a voice-session token for an expert, to hand to your own frontend. | | Send to meetings | `meetings:join` | Send an expert into a Google Meet, Zoom or Microsoft Teams call. | | Use as an AI tool (MCP) | `mcp:use` | Let Claude, Cursor and other MCP clients use your experts as tools. | There is no webhook scope. Webhook endpoints are managed in the app only. See [Webhooks](/developers/webhooks). ## Common routes by scope The [API reference](/api-reference) lists every route with the scope it needs. These are the ones most integrations start with. | Scope | Routes | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `experts:read` | `GET /v1/agents`, `GET /v1/agents/{id}`, `GET /v1/agents/{id}/versions` | | `experts:write` | `POST /v1/agents`, `PATCH /v1/agents/{id}`, `POST /v1/agents/{id}/publish` | | `knowledge:read` | `GET /v1/agents/{id}/kb`, `GET /v1/agents/{id}/kb/search` | | `knowledge:write` | `POST /v1/agents/{id}/kb`, `POST /v1/agents/{id}/kb/file`, `POST /v1/agents/{id}/kb/faq`, `DELETE /v1/kb/docs/{docId}` | | `tools:read` | `GET /v1/workspace-tools`, `GET /v1/workspace-tools/{id}/calls` | | `conversations:read` | `GET /v1/chat/conversations`, `GET /v1/chat/conversations/{id}/messages` | | `conversations:write` | `DELETE /v1/chat/conversations/{id}` | | `chat:write` | `POST /v1/chat/conversations`, `POST /v1/chat/conversations/{id}/messages`, `GET /v1/chat/conversations/{id}/stream` | | `voice_sessions:write` | `POST /v1/voice/sessions` | | `meetings:read` | `GET /v1/meetings`, `GET /v1/meetings/{id}`, `GET /v1/meetings/{id}/summary` | | `meetings:write` | `POST /v1/meetings/{id}/leave`, `POST /v1/meetings/{id}/cancel` | | `meetings:join` | `POST /v1/meetings` | | `analytics:read` | `GET /v1/analytics/usage`, `GET /v1/analytics/overview` | | `mcp:use` | `POST /mcp/experts/{id}` | > **Note** > > The API calls experts "agents" in its paths: `/v1/agents/{id}` is an expert. ## What keys can't do Some routes are for people signed in to the app, never for keys. They include: * creating, rotating or revealing API keys, and managing service accounts; * managing webhook endpoints and reading their delivery log; * deleting or duplicating an expert, and resetting its public link; * phone numbers, phone calls and campaigns; * emailing a meeting summary; * members, billing and workspace settings. A key sent to one of them is refused with `403` and `error: "not_available_to_api_keys"`. That goes for single routes next to key-accessible ones (deleting an expert, for example) and for whole app-only sections (Developers, billing, workspace settings). ## Pick the smallest set Give each key only what its job needs: | Job | Scopes | | ---------------------------------------------- | ---------------------------------------------------------- | | Chat with an expert from your backend | `chat:write` (add `conversations:read` to read past chats) | | Voice calls in your own frontend | `voice_sessions:write` | | Keep an expert's knowledge in sync | `knowledge:write` | | Send an expert to meetings from your scheduler | `meetings:join`, plus `meetings:read` to fetch the summary | | Use an expert from Claude or Cursor | `mcp:use` plus `chat:write` and `knowledge:read` | | A reporting dashboard | `analytics:read` |