Permissions

Each API key has an explicit list of scopes, chosen when you create it. Nothing is implied: a write scope does not include the matching read scope, so a key that replies to conversations and also reads them needs both conversations:write and conversations:read.

Scope	Allows
conversations:read	List and read conversations and messages, internal notes included.
customers:read	List and read customers, including their email address.
help-center:read	List and read collections and articles (drafts too), and search published articles.
feedback:read	List and read boards, posts and comments.
changelog:read	List and read changelog entries. Drafts only when you ask for them.
knowledge:read	List the knowledge sources the AI agent learns from.
credits:read	Read the AI credit balance.
ai:ask	Ask the AI agent a question.
conversations:write	Reply to customers, add internal notes and close conversations.
help-center:write	Create article drafts. Never publishes.
feedback:write	Create feedback posts.

What each endpoint needs

Endpoint	Scope
GET /api/v1/workspace	none, a valid key is enough
GET /api/v1/conversations, /conversations/{id}, /conversations/{id}/messages	conversations:read
POST /api/v1/conversations/{id}/messages, /conversations/{id}/close	conversations:write
GET /api/v1/customers, /customers/{id}	customers:read
GET /api/v1/help-center/collections, /help-center/articles, /help-center/articles/{id}, /search	help-center:read
POST /api/v1/help-center/articles	help-center:write
GET /api/v1/feedback/boards, /feedback/posts, /feedback/posts/{id}	feedback:read
POST /api/v1/feedback/posts	feedback:write
GET /api/v1/changelog, /changelog/{id}	changelog:read
GET /api/v1/knowledge/sources, /knowledge/sources/{id}	knowledge:read
POST /api/v1/ask	ai:ask
GET /api/v1/credits	credits:read

Two things to remember

• A key with conversations:write can send a message that customers read. When an action might reach a customer, the endpoint page says so. Give that scope only to code you trust.
• Articles you create through the API are always drafts. A person publishes them in Tirver.

If a key lacks the scope an endpoint needs, the API answers 403 with the code insufficient_scope, and the message names the scope. If a workspace has switched a module off, such as the help center, its endpoints answer 404 with module_disabled. See errors.