Concepts

Kit

A Kit is Ketvia’s equivalent of a Slack app. It has a global identity (an id and a slug) and is described by a manifest. The Kit’s code runs on the developer’s own servers; Ketvia never hosts or executes it.

Kits have a distribution:

Distribution	Meaning	Available
private	Created by an admin of one workspace and installed only there.	Now
unlisted	Installable by any workspace that has the install link.	Later phase
directory	Reviewed and listed in the Kit directory.	Later phase

Manifest

The manifest is a JSON document that declares what the Kit is and what it may do: its names, developer, the scopes its bot and its users may hold, incoming webhooks and OAuth redirect URLs. It is a consent document, so it is strict: unknown keys are rejected, URLs must be https, and display strings are localized (en required, tr optional).

Each manifest carries a version (major.minor.patch). Uploading the same slug with a higher version updates the Kit, and the workspace installation moves to the new version. See the manifest reference.

Installation

An installation is one Kit version installed in one workspace. It owns the Kit bot, the tokens issued for the Kit in that workspace and its incoming webhooks. An installation always belongs to exactly one workspace; a token never reaches another workspace.

Installing a Kit enables nothing on its own: the Kit bot sees no channel until an admin adds it to one, and no token exists until one is created or authorized.

The Kit bot and assistants

Every installation that requests bot scopes has a Kit bot: the identity that authors the Kit’s messages. A Kit bot is not an assistant. Ketvia’s assistants are AI bots with their own prompts and permissions; a Kit bot never runs a model and never answers questions. It only does what the Kit’s code does through the Web API or a webhook.

A Kit bot works only in channels it has been added to. Admins add it on the Kit’s API access page, and only to channels they are members of themselves. Creating an incoming webhook for a channel also adds the Kit bot there.

Bot tokens and user tokens

	Bot token (kbot_…)	User token (kusr_…)
Acts as	The Kit bot	One member
Sees	Only channels the Kit bot was added to	What that member can see
Edits/deletes	Only its own messages	Only that member’s messages
Scopes	The manifest’s bot.scopes	The manifest’s userScopes
Lifetime	No expiry; rotate or revoke	1 hour, renewed with a single-use refresh token
Obtained by	An admin on the API access page, or kit.access (bot)	The member allowing it in kit.access (user, with PKCE)

A user token also ends when the member’s web session that authorized it ends. Some actions are user-only in v1: Kit bots cannot add reactions or upload files yet, so use a user token for those. See Tokens and authentication.

Scopes

A scope is a permission string such as messages:write. A token can only call methods whose scope it holds, and never more than the installed manifest version requests. Bot and user scope sets are separate. A scope never bypasses membership: messages:read on a bot token reads only channels the Kit bot was added to.

There are deliberately no admin scopes: a Kit cannot manage members or channels, read the audit log, or approve anything. See Scopes.

Consent

Every grant of access is an explicit human decision:

• An admin creates the private Kit from its manifest and installs it. The scopes in the manifest are the most the Kit can ever get in that workspace.
• An admin adds the Kit bot to channels, creates bot tokens and creates incoming webhooks.
• For user tokens, each member decides for themselves on Ketvia’s authorization page; the token is bounded by that member’s own access.

Revocation

Revocation is immediate:

• A revoked bot token stops working at once (401 invalid_token).
• A revoked incoming webhook answers 404 at once.
• A new manifest version that drops a scope narrows existing tokens at once.
• Reusing a user refresh token revokes the whole grant (access and refresh tokens).
• Uninstalling the Kit revokes all its tokens and disables its webhooks.

Security model

• Secrets are shown once and stored hashed. Bot tokens, user tokens, refresh tokens, client secrets and webhook URL secrets appear only in the response that creates them. Ketvia keeps a hash; a lost secret is replaced, never recovered.
• 404, not 403, for anything you cannot see. A token that is not allowed to see a conversation, message, file or member gets 404 not_found, exactly as if it did not exist. 403 is only about what the token is (missing scope, or a token type that cannot do this), never about whether something exists.
• Tenant isolation. The workspace is implied by the token. Every query is bound to that workspace by the database’s row-level security; no request parameter can reach another workspace.
• No data to the AI model. Nothing a Kit reads or writes through the Web API or a webhook is sent to Ketvia’s language model on the Kit’s behalf, and private assistant results are never returned by the Web API.
• No remote content in messages. Blocks cannot load remote images; image blocks reference Ketvia files only.

Next: the security checklist for your own Kit.