App platform | Kweko Developers

App platform

Apps extend Kweko for many workspaces at once: they call the API with OAuth tokens, get lifecycle webhooks, and add their own UI inside Kweko with blocks or frames.

How an app fits together

Piece	What it is
App record	Name, icon, description, category, scopes, redirect URIs, your backend URL and the UI you contribute. You edit it in the developer console at `https://app.kweko.uz/developers`.
OAuth 2.0 with PKCE	When a workspace installs your app, your server gets an access token and a refresh token for that workspace. See OAuth for apps.
Blocks	Small native UI (cards, lists, buttons, forms, tables, charts) that your backend returns as JSON and Kweko draws with its own components. See Blocks.
Frames	Your own web page inside Kweko, in a sandboxed iframe, talking to Kweko through `@kweko/sdk`. See Frames and the SDK.
Lifecycle webhooks	`app.installed`, `app.scopes_changed` and `app.uninstalled`, sent to your webhook URL and signed with your client secret. See OAuth for apps.

An app that only syncs data needs just OAuth and the API. UI is optional.

Extension points

Your app adds UI through contributions: each one names an extension point, how it renders and a localized title. The catalog, generated from the API:

Extension point	Render as	Gets the record
`nav.sidebar`	`link`	No
`page.full`	`frame`, `blocks`	No
`lead.tab`	`blocks`, `frame`	Yes
`lead.panel.card`	`blocks`	Yes
`contact.tab`	`blocks`, `frame`	Yes
`record.action.menu`	`blocks`, `frame`	Yes
`list.bulk.action`	`blocks`, `frame`	Yes
`composer.mode`	`blocks`, `frame`	Yes
`timeline.item`	`blocks`	Yes
`dock.widget`	`blocks`, `frame`	No
`dashboard.widget`	`blocks`, `frame`	No
`settings.page`	`schema`, `frame`	No

link (only nav.sidebar) adds a sidebar entry that opens one of your page.full contributions (target).
schema (only settings.page) renders a settings form from your app's settings schema.
Points that get the record receive it in their context as entity (type and id, or ids for bulk actions).
Kweko shows these today: nav.sidebar, page.full, lead.tab, lead.panel.card, record.action.menu, composer.mode, dock.widget and settings.page. The others (contact.tab, list.bulk.action, timeline.item, dashboard.widget) are accepted in the manifest but not shown anywhere in Kweko yet.

A contribution has an id (lowercase letters, digits, _ and -, up to 40 characters, unique in the app), point, render, title (by language, up to 60 characters), and for frames a path on your backend. An app can have up to 30 contributions.

Start building

Sign in at https://app.kweko.uz/developers and create a vendor account (a name, and optionally a website and support email).
Create an app. Copy the client secret (kwk_cs_…) now: it is shown once. The app's id (app_…) is its OAuth client id.
Add a redirect URI, the scopes you need, your backend URL and, if you add UI, your contributions.
Test install the app into a workspace where you are an owner or admin. Only you can install an app before it is published.
When it works, submit it for review.

The SDK

@kweko/sdk has two entry points: @kweko/sdk for code inside a frame, and @kweko/sdk/server for your backend (signature checks, PKCE and token helpers, and types for blocks). It is plain ESM with no dependencies and runs in browsers, Node 18+, Deno, Bun and Workers.

The package lives in the Kweko repository (packages/sdk) and is not on npm yet. Until it is, the protocols below are all you need: every helper is a few lines you can write yourself.