Security checklist

Before you give a Kit to a workspace, check each item.

Least privilege

• The manifest requests only the scopes the Kit uses. Drop users:read.email unless you need email addresses.
• The Kit bot is added only to the channels it needs.
• Use a bot token for automation and a user token only when the Kit must act as a specific member.

Secrets

• Bot tokens, user and refresh tokens, client secrets and webhook URLs live in a secret store or CI secret, never in source code, logs, error reports or chat.
• Tokens are used only from your backend; no token or client secret reaches a browser or mobile app.
• Your logs and error trackers redact Authorization headers and webhook URLs.
• You know how to rotate: POST /auth/rotate for bot tokens (24 hours of overlap), a new client secret (24 hours of overlap), revoke and recreate for webhooks.
• Anything that may have leaked is revoked at once; revocation is immediate.

kit.access

• state is random per request and checked on the redirect.
• User authorizations use PKCE (S256) with a fresh verifier per request.
• Redirect URLs are https endpoints you control, listed exactly in oauth.redirectUrls.
• Refresh tokens are used once and replaced; concurrent refreshes for the same member are serialized.

Requests and data

• Retries of POST /messages carry an Idempotency-Key, and you honour Retry-After on 429.
• A 404 is treated as “not visible to this token”, not as a reason to try other ids.
• Data read through the Web API is stored only as long as the Kit needs it, as your privacy policy states.
• Every message sets text, and Blocks contain no secrets or personal data the channel should not see.

Incoming requests (events, interactions, commands)

• Verify Ketvia-Signature over the raw body (createKitServer does this), reject requests older than 300 seconds, and accept two secrets during a rotation.
• Dedupe events on eventId; treat sequence as the order.
• Derive the tenant from Ketvia-Installation-Id, never from a value in the payload alone.
• Keep the responseUrl secret: it is a credential for 30 minutes. Never log it.
• Answer 2xx within 3 seconds and do slow work in the background.

Developer tokens and secrets

• Developer tokens (kdev_…) live in a secret store or CI secret, one per machine or job, and are revoked when no longer needed. They expire after 90 days by default.
• The signing secret (kss_…) and client secret (kcs_…) are kept server-side only. During a rotation the old signing secret stays valid for 7 days and the old client secret for 24 hours: deploy the new one inside that window.
• ketvia kits dev runs against a tunnel you control, in the sandbox, never against a production workspace.