Scopes | Rydhm Docs

Every API key carries a list of scopes. A scope is written <resource>:<level>, 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.

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.
Expert limits apply on top. A key limited to some experts is refused for every other expert, whatever its scopes. See Expert-restricted keys.

When a key lacks a scope, the API answers 403 with error: "insufficient_scope" and names what is missing:

{
  "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.

Common routes by scope

The 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}`

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`