Publishing

Publishing an app makes it available for other Kazzle spaces to discover and install.

What publishing does

Publishing makes the app installable by other spaces. People see the app’s name, icon, publisher, and visibility, then install it into their own space. The published version uses the latest commit on main. There is no separate release branch for published apps. By default, clicking a published app opens its deployed UI. Apps can optionally set a custom launch URL, require Kazzle identity before opening, or receive install and uninstall webhooks. See Build and publish for how to publish an app.

Installs

When someone installs a published app, Kazzle creates an installation record inside their space. The installing space owns the installation and any data associated with it.

User identity

When a logged-in Kazzle user opens an installed app, Kazzle provides the app with information about the current user. Kazzle attaches a short-lived JWT as a bearer token. The app can verify the token against Kazzle’s public JWKS to read the user, space, and install. The token contains these claims:

Claim	Meaning
`aud`	`kazzle:app`
`iss`	`https://api.kazzle.app`
`sub`	Kazzle user ID
`user`	`{ id, email }` of the user
`space`	ID of the space the app is installed in
`install`	ID of this specific installation

Example verification:

import { jwtVerify, createRemoteJWKSet } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://api.kazzle.app/auth/.well-known/jwks.json'));

async function getUserFromToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    audience: 'kazzle:app',
    issuer: 'https://api.kazzle.app',
  });
  return payload;
}

Two fields in the app manifest control launch behavior for published apps:

kazzleAuth: required means only logged-in Kazzle users can open the app; optional allows the app to be opened without a Kazzle identity.
launchUrl: overrides the entry point that opens when a user clicks the app.

Webhooks

If the manifest includes a webhookUrl, Kazzle sends HTTP POST requests to it when the app is installed or uninstalled. app.installed includes the install key the publisher’s backend can use to authenticate to the per-install API:

{
  "event": "app.installed",
  "installId": "...",
  "appId": "...",
  "spaceId": "...",
  "apiUrl": "https://api.kazzle.app",
  "installKey": "kzl_inst_...",
  "user": { "id": "...", "email": "..." }
}

app.uninstalled contains the event, install ID, app ID, space ID, and API URL. The publisher should stop using the install key after receiving this event.

Per-install API

Each installation can call a scoped API on https://api.kazzle.app. Calls are authenticated with either the install key (from the publisher’s backend) or the user identity token (from the hosted UI). All operations are automatically scoped to that install. Available endpoints: Full request and response schemas are published in the Kazzle OpenAPI spec at https://api.kazzle.app/openapi.json under these paths.

Method	Path	Description
GET	`/apps/secrets`	List secret names stored for the install
GET	`/apps/secrets/:name`	Read a secret value
PUT	`/apps/secrets/:name`	Store a secret value
DELETE	`/apps/secrets/:name`	Delete a secret
GET	`/apps/metadata`	Read non-secret metadata for the install
PUT	`/apps/metadata`	Merge updates into the install’s metadata

Secrets written through this API are encrypted at rest and isolated to the specific installation. They are separate from secrets stored in a space’s vault.

Next steps

Build and publish — how to build, iterate, and publish an app.
Configuration — full manifest reference, including kazzleAuth, launchUrl, and webhookUrl.

​Publishing

​What publishing does

​Installs

​User identity

​Webhooks

​Per-install API

​Next steps