Publishing

Your app becomes installable the moment it’s in the platform’s App Store catalog. Registration is how it gets there: you hand the platform your manifest and your public URL, and from then on every merchant who clicks Install gets your app provisioned into their workspace automatically — no key to paste, no support ticket. This page covers what the platform needs from you, what it does on each install, the checklist to run before you submit, and the config each environment expects.

What the platform needs from you

Two things, and neither is a secret:

Your manifest (sentralbee.app.json) — provider, scopes, embed path, webhooks, and optional checkout. This is the whole declaration of what your app is and what it may do. See The manifest.
Your app’s public HTTPS URL — the origin where the platform reaches /install/provision and /install/uninstall, serves your embed, and (if you declared checkout) calls your create-checkout endpoint.

There’s deliberately no shared secret to exchange. The platform holds the Ed25519 private key and signs tokens with it; your app holds only the matching public key and verifies them. That asymmetry is the trust model — an app can check that a token is genuine but can never forge one. See Concepts & lifecycle.

Today: registration is assisted

A self-serve developer portal is on the roadmap. Until it lands, registration is a short handoff: send your manifest and your public URL to the Sentralbee team, and your app is added to the catalog.

Reach out to the Sentralbee team with your sentralbee.app.json and your app’s public HTTPS origin to get listed.

Once you’re in the catalog, nothing about your app is manual again. Every time a merchant installs, the platform:

auto-mints an API key (kind app) carrying exactly the scopes the merchant consented to on the install screen,
delivers it to POST /install/provision — a one-time, server-to-server call whose body is { apiKey, webhookSecret? } (the webhookSecret is included only if your manifest declares webhooks),
hands the merchant your embed — opening it with a live session token via the host bridge.

Your onProvision handler encrypts and stores that key; your embed reads the session token and calls your own API with it. If any of that is unfamiliar, Install lifecycle walks through the handlers in code.

The pre-submit checklist

Run through this before you hand off your manifest. Most of it the starter already does for you; this is the list to verify, not to build from scratch.

sentralbee manifest passes — your sentralbee.app.json is valid.
bun run typecheck and your tests pass.
You request the minimum scopes your app needs. Merchants see every scope on the consent screen, so asking for less is asking for trust you’ll actually get.
/install/provision stores the delivered key encrypted with createCypher — never in plaintext — and is idempotent, so a retried provision is safe.
/install/uninstall purges everything you hold for the workspace.
Webhook handlers call verifyWebhookSignature over the raw body and fail closed on a bad signature. See Webhooks.
Your embed works in both light and dark themes and always reads the workspace from the verified session token, never from the request body.
No secret — the provisioned key, the webhook secret, your APP_KEY — is ever logged.

Configure each environment

The same code runs in every environment; only the config changes. Point your app at the right key and API base for wherever it’s deployed. These come from the environment — never hardcode them.

Variable	What it is
`PLATFORM_JWT_PUBLIC_KEY`	The platform’s Ed25519 public key (PEM) for that environment. Your app verifies session and provision tokens with it. In `sentralbee dev` this is a throwaway dev key; in production it’s the real platform key.
`SENTRALBEE_API_URL`	The public API base. Defaults to `https://api.sentralbee.app`; point it at a dev gateway locally.
`APP_KEY`	Your app’s own encryption secret — any high-entropy string — used to encrypt stored secrets at rest. Never commit it. Rotate by re-provisioning.

The starter reads all three in api/src/config.ts, and the factories fail closed: with no key set, the app refuses to verify tokens or decrypt secrets rather than falling back to something guessable.

export const SENTRALBEE_API_URL = process.env.SENTRALBEE_API_URL ?? "https://api.sentralbee.app";

// Verifies platform session/provision tokens (Ed25519).
export const verifier = createTokenVerifier({
    publicKeyPem: process.env.PLATFORM_JWT_PUBLIC_KEY ?? "",
    audience: manifestAudience(manifest as AppManifest),
});

// Encrypts/decrypts your stored secrets (the provisioned api key, etc.).
export const cypher = createCypher(process.env.APP_KEY ?? "");

APP_KEY is yours, not the platform’s. It’s how you encrypt the api key the platform gives you. If you lose it you can’t decrypt your stored keys — but that’s recoverable: rotating APP_KEY and letting each workspace re-provision re-delivers a fresh key. Losing it is inconvenient, not catastrophic.

Where to next

Quickstart — build and run the app you’re about to publish.
The manifest — the file registration reads.
Install lifecycle — the provision and uninstall handlers in code.
Concepts & lifecycle — the trust model behind registration.

Get Started

Build your app

Reference

What the platform needs from you

Today: registration is assisted

The pre-submit checklist

Configure each environment

Where to next

​What the platform needs from you

​Today: registration is assisted

​The pre-submit checklist

​Configure each environment

​Where to next

What the platform needs from you

Today: registration is assisted

The pre-submit checklist

Configure each environment

Where to next