Scopes

A scope is a permission string that a Kit requests in its manifest: bot scopes in bot.scopes, user scopes in userScopes. The two sets are separate. A token holds the scopes granted when it was issued, limited to what the installed manifest version still requests; GET /auth/test shows them.

Rules

• A scope never bypasses membership. A bot token sees only channels the Kit bot was added to. A user token sees only what its member can see.
• Own messages only. messages:write edits and deletes only messages the token’s actor posted.
• Missing scope: 403 with code missing_scope and the header X-Ketvia-Required-Scope: <scope>.
• Wrong token type: 403 with code forbidden. In v1, Kit bots cannot add or remove reactions or upload files; use a user token for those even if the bot holds the scope. GET /runs/{id} takes user tokens only.
• Least privilege. Request only what the Kit uses. Every scope is shown to the admin who installs the Kit, and users:read.email is shown as sensitive.

Catalogue

The method column is generated from the Web API route table. Methods without a scope (GET /auth/test, POST /auth/rotate, GET /users/me, GET /installation) work with any valid token of the right type.

Scope	Bot	User	Grants	Web API methods
conversations:read	Yes	Yes	List conversations the actor is in and read their metadata and members.	GET /conversations GET /conversations/{id} GET /conversations/{id}/members
messages:read	Yes	Yes	Read message history and threads in those conversations. Private assistant results are never included.	GET /conversations/{id}/messages GET /messages/{id} GET /messages/{id}/replies
messages:write	Yes	Yes	Post messages (with Blocks), and edit and delete the actor’s own messages.	POST /messages PATCH /messages/{id} DELETE /messages/{id}
messages:write.ephemeral	Later phase (no v1 method)	–	Post messages visible to one member only.	POST /messages/ephemeral
reactions:read	Yes	Yes	Read reactions.	None in v1
reactions:write	Yes (method refused for bots in v1)	Yes	Add and remove the actor’s own reactions.	POST /reactions DELETE /reactions
files:read	Yes	Yes	Read file metadata and content in visible conversations.	GET /files/{id} GET /files/{id}/content
files:write	Yes (method refused for bots in v1)	Yes	Upload files.	POST /files
users:read	Yes	Yes	Read the member directory: id, display name and role.	GET /users GET /users/{id}
users:read.email	Yes	Yes	Adds email addresses to member records. Shown as sensitive at install.	Adds email to the users:read methods
commands	Later phase	–	Register the manifest’s slash commands.	None in v1
incoming-webhook	Yes	–	Incoming webhooks into channels chosen by an admin.	Incoming webhook URLs
assistant:tools	Later phase	–	Expose the manifest’s tools to Ketvia assistants.	None in v1
runs:read	–	Yes	Read the member’s assistant runs (private runs only for their requester).	GET /runs/{id}

Private Kits in this phase may request these bot scopes: conversations:read, messages:read, messages:write, reactions:read, reactions:write, files:read, files:write, users:read, users:read.email and incoming-webhook, commands and messages:write.ephemeral, plus any user scope. assistant:tools is rejected until a later phase. messages:write.ephemeral is the scope of POST /messages/ephemeral.

No admin scopes

There are deliberately no admin scopes: no scope lets a Kit manage members or channels, read the audit log, change assistant permissions, or create, approve or reject approvals.