Extensions
Extensions are first-class platform resources. Not a v1 applets-mode and not a webhook — an extension is an installable module that adds a complete surface (Console UI, runtime API, optional background logic) on top of the core platform, consuming the same auth, RBAC, and data primitives as any core platform feature. The contract is uniform across all extension classes.
Kilimanjaro ships four Trailblazer-class extensions as reference implementations: Paperless, Context, Lookout, and Gate Studio. The framework spec below is what any extension installs against — whether Kilimanjaro-built or third-party.
Extension classes
Extensions belong to one of three classes, set by integration depth:
| Class | Basis | Members |
|---|---|---|
| Trailblazer | The Console is aware of the extension and is noticeably incomplete without it: flagship functionality compartmentalised into an extension | Paperless, Context, Lookout, Gate Studio |
| Anchor | An activation wrapper over in-built platform functionality | Every Data Bridge and every Event Bridge |
| Circuit | Every other extension | For example Stripe, Slack, Teams, Twilio and Brand Studio |
The same framework specification, manifest schema, lifecycle, and runtime contract apply to every extension in every class. Class describes how deeply the platform integrates an extension; it is not a quality tier or a partner tier. Whether an extension is featured in the Hub is a separate axis and does not depend on class.
1. The extension entity
1.1 Identifiers
| Identifier | Shape | Use |
|---|---|---|
| Slug | Lowercase alphanumeric with hyphens ([a-z0-9-]+, no leading/trailing hyphen, no double hyphens, max 64 chars). Permanent for the lifetime of the extension. | URL namespace on both two-namespace classes — API class (<orgSlug>.api.k9o.io/@<projectSlug>/extensions/<slug>/...) for dynamic routes; user-content host (https://<label>-cdn-<rgn>.<usercontent-domain>/extensions/<slug>/<version>/..., where the label is an opaque per-(project, extension) value) for static files |
| Internal ID | ext_<base62> per the conventions resource-ID catalogue | Internal references (audit logs, error context, foreign keys); SDK callers may pass either form |
The platform reserves a small slug set:
- Trailblazer-class slugs —
paperless,context,lookout,gate-studio - Hard-blocked —
admin,core,system,platform,kibo,console,auth.
Reserved-slug attempts return K9O_EXTENSION_SLUG_RESERVED (409) at registration.
1.2 Two-scope model
Extensions live at two distinct scopes:
| Scope | Action | Authority | Effect |
|---|---|---|---|
| Org | register | ORG_ADMIN+ | Adds the extension to the org's available-extensions registry. Discoverable and installable but not active on any project. |
| Project | enable | PROJECT_ADMIN+ | The moment manifest permissions are reviewed and granted, the per-project SQL schema is provisioned, and a per-project plugin token is issued. |
The two-scope split exists because extension trust does not transitively flow from org to project: an org admin's registration does not authorise the extension to read or write any specific project's data. Each project independently approves the permission grant.
Platform-curated extensions are pre-registered in every org's registry. Third-party publishing flows through the curation programme — see Build Your Own → Publishing and curation.
2. Manifest schema
Every extension ships a declarative manifest.json that the platform reads at registration and re-validates on every version update. Format: JSON.
{
"manifest_version": 1,
"slug": "forms",
"name": "Forms",
"version": "1.0.0",
"publisher": {
"name": "Formelo Inc.",
"url": "https://kilimanjaro.dev"
},
"description": "Design forms in the Console, collect data through Paperless.",
"listing": {
"appIconUrl": "https://.../brand/extensions/forms/app-icon.png",
"bannerUrl": "https://.../brand/extensions/forms/banner.png",
"previewUrls": ["https://.../preview-1.png", "https://.../preview-2.png"],
"tagline": "Design forms in the Console, collect data anywhere.",
"description": "A 100–200 word Markdown how-it-works body shown on the Hub detail page."
},
"permissions": [
{ "domain": "documents", "action": "write", "qualifier": "*" },
{ "domain": "collections", "action": "read", "qualifier": "*" },
{ "domain": "users", "action": "read", "qualifier": "*" }
],
"surfaces": {
"console": {
"routes": ["/console/extensions/forms/*"],
"bundle": "./dist/forms-console.js"
},
"runtime_api": {
"prefix": "/api/forms",
"spec": "./dist/openapi.json",
"function": "forms-runtime"
},
"background_logic": {
"functions": [
{ "name": "forms-runtime", "runtime": "bun", "tier": "sandbox", "entry_point": "./dist/runtime.js" }
]
}
},
"static_files": "static",
"compatibility": {
"tokenset_version_min": "2.4.0",
"shadcn_version_min": "0.9.0"
},
"custom_tokens": {
"--ext-forms-accent": "#2563eb",
"--ext-forms-field-radius": "6px"
},
"schema": {
"tables": ["templates", "submissions_cache"],
"migrations": "./dist/migrations/"
},
"hooks": {
"enable": { "url": "POST /hooks/enable" },
"configure": { "url": "POST /hooks/configure" },
"activate": { "url": "POST /hooks/activate" },
"deactivate": { "url": "POST /hooks/deactivate" },
"purge": { "url": "POST /hooks/purge" },
"monitor": { "url": "GET /hooks/monitor" },
"data_export": { "url": "POST /hooks/data_export" }
}
}
2.1 Top-level fields
| Field | Type | Required | Description |
|---|---|---|---|
manifest_version | integer | Yes | Schema version of the manifest format. Currently 1; subsequent bumps deprecate prior versions on a 12-month overlap. |
slug | string | Yes | Globally unique slug per §1.1. |
name | string | Yes | Display name (max 64 chars). |
version | string | Yes | Semantic version (major.minor.patch). |
publisher | object | Yes | { name, url }. |
description | string | Yes | Short internal description (max 280 chars). |
listing | object | Yes | Marketplace listing content — appIconUrl, bannerUrl, previewUrls[], tagline, and a 100–200 word Markdown description. A manifest missing it fails validation. |
permissions | object[] | Yes | Permission grants (§2.2). May be empty for surface-only extensions that touch no project data. |
surfaces | object | Yes | console, runtime_api, and background_logic sub-objects (§2.3). At least one must be non-null. |
static_files | string | Optional | Directory path (relative to extension bundle root) containing static files served from the user-content host (https://<label>-cdn-<rgn>.<usercontent-domain>/extensions/<slug>/<version>/...). Default "static". Contains Console iframe bundles at <static_files>/iframe/<surface-name>/ plus brand assets and any other static content. Extensions don't declare an origin — the user-content host is platform-managed. |
compatibility | object | Optional | Host-version expectations for your Console iframe (§2.6). Omit if your UI doesn't depend on a specific host design-system version. |
custom_tokens | object | Optional | Default CSS custom-token values for your iframe, namespaced to your slug (§2.6). Omit if your UI doesn't theme against host tokens. |
schema | object | null | Optional | Per-project SQL-schema declaration (§2.4); null if the extension stores no data. |
hooks | object | Optional | Lifecycle-hook declarations (§2.5). |
2.2 Permissions vocabulary
Permissions are (domain, action, qualifier) triples. The vocabulary is a closed enumeration; new permission types follow the standard breaking-change discipline.
domain | Allowed action values | qualifier semantics |
|---|---|---|
documents | read, write, delete | Collection slug list or "*" |
collections | read, write | Collection slug list or "*" |
attributes | read, write | Collection slug list or "*" |
vectors | read, write | Collection slug list or "*" |
users | read | Role filter (e.g., "PROJECT_MEMBER") or "*" |
identities | read | "*" only |
groups | read | "*" only |
files | read, write, delete | Bucket name list or "*" |
storage | read, write | Bucket name list or "*" |
webhooks | subscribe | Event-name list (e.g., ["document.created"]) |
functions | invoke | Function-name list or "*" |
auth_flows | read, write | "*" only |
views | read, write | View slug list or "*" |
telemetry | read | "*" only |
bridge.cdc | subscribe | Collection slug list or "*" |
bridge.sync | write | Collection slug list or "*" |
bridge.credentials | read | Binding-id list or "*" |
tables | create, schema | Always implicitly the extension's own per-project schema; qualifier reserved for cross-extension sharing and must be "_self" |
A permission grant authorises the extension's plugin token to perform the named action on resources matching the qualifier — and only via the gateway API. Enforcement is at the platform's RBAC + JSON-policy layer: the extension's token presents subject.role = "extension", the gateway checks the manifest grant, and the project's JSON policy is evaluated as the second layer per Control.
A project's enable binds the manifest's permission set at that moment. A subsequent version bump that adds new permissions requires re-authorisation. An update that does not add permissions auto-applies within the major version.
2.3 Surfaces declaration
Extensions live on the two-namespace canonical — the API class (<orgSlug>.api.k9o.io) for dynamic routes, the user-content host (<label>-cdn-<rgn>.<usercontent-domain>) for static files. Each extension declares which surfaces it contributes to:
-
surfaces.console— React components mounted at/console/extensions/<slug>/*Console routes. Loaded into a sandboxed iframe whosesrcis constructed from the user-content host athttps://<label>-cdn-<rgn>.<usercontent-domain>/extensions/<slug>/<version>/<iframe_path>(see §5.3 Console iframe embedding). Required fields:routes(path patterns the extension owns within the Console namespace) andbundle(path to the Console bundle). Iframe bundles live under the manifest's top-levelstatic_filesdirectory at<static_files>/iframe/<surface-name>/; the platform publishes the directory to the user-content host at install time. Null when the extension has no Console UI. -
surfaces.runtime_api— the extension's runtime API, declared as a mountprefixplus a bundled OpenAPIspec:Field Description prefixThe API mount point; it must be /api/<slug>. The gateway mounts it at<orgSlug>.api.k9o.io/@<projectSlug>/extensions/<slug>/<prefix>/...and forwards every matching request to the extension runtime, which routes internallyfunctionName of the host function that serves the extension. Required when the manifest declares hooks; it must match a sandbox entry of the same name inbackground_logic.functions[], and a manifest that declares hooks without it is refused withK9O_EXTENSION_MANIFEST_INVALIDspecPath (relative to the bundle) to an OpenAPI document describing each route — its method, path, and a per-operation permission_scopecross-referencing a manifest permission (§2.2)The platform validates the manifest shape and that
specis valid OpenAPI at install time; it does not validate request or response bodies at runtime, so the extension's routes can ship on their own release cadence behind the mounted prefix. Null when the extension exposes no runtime API. (This replaces the earlier per-routeruntime_routes[]array, in which the platform mounted each route to a named handler.) -
surfaces.background_logic— declared functions and workflows the extension owns:functions[]— list of function descriptors per Compute. Functions deploy under the extension's(project, extension)enable and follow the extension function lifecycle (§3.3).runtime_tier?: "wasm" | "container" | null— opt-in to a runtime-hosting tier where the platform hosts the extension's running process. Both"wasm"(Bun + WebAssembly sandbox) and"container"(Firecracker microVM) are first-class at v2 launch.null(or absent) means the extension's backend runs on partner-side infrastructure (legacy proxy path).
At least one of the three surfaces must be non-null.
2.3.1 webhookIngress[] — inbound webhook handlers
Extensions that receive inbound webhooks from third-party systems (Stripe, GitHub, Slack, Atlassian, etc.) declare a webhookIngress[] array. Each entry binds an inbound endpoint to a verification scheme:
"webhookIngress": [
{
"path": "/webhooks/stripe",
"signatureScheme": "stripe-v1",
"signatureHeader": "Stripe-Signature",
"enabled": true
},
{
"path": "/webhooks/atlassian",
"signatureScheme": "atlassian-jwt",
"signatureHeader": "Authorization",
"enabled": true
}
]
Per entry:
| Field | Description |
|---|---|
path | Path the third-party sender posts to, under the extension's runtime prefix; full URL is <orgSlug>.api.k9o.io/@<projectSlug>/extensions/<slug><path> |
signatureScheme | One of 12 standard schemes — stripe-v1, github-hmac-sha256, slack-v0, sendgrid-v3-ed25519, twilio, shopify, linear, notion, discord, ms-teams, generic-hmac-sha256, atlassian-jwt — or the custom escape value. The gateway verifies signatures using this scheme before dispatching to the extension |
signatureHeader | Name of the request header that carries the signature. Required for every scheme except figma, where it must be omitted |
enabled | Required boolean; false keeps the declaration but accepts no deliveries |
The signing secret for each webhook ingress is stored in Kibo's software-protected managed key store (with hardware-attested custody, secret custody moves to a FIPS 140-3 Level 3 HSM-backed enclave), referenced from the per-project k9o_<proj_id>_ext_<slug>.webhook_secrets table. Extension code never holds the raw secret; the gateway performs verification before any extension function runs. Failed verification returns K9O_WEBHOOK_SIGNATURE_INVALID (401) to the caller without invoking the extension.
The custom escape value places the extension on a guarded path — Warden review at publication, Console disclosure to the project admin — for vendor schemes the platform has not standardised. Full treatment of the verification model is at Security → Webhook signature verification.
2.4 Schema declaration
Extensions that store data declare a relative table list and a migrations directory:
"schema": {
"tables": ["templates", "submissions_cache"],
"migrations": "./dist/migrations/"
}
The per-project schema name is k9o_<proj_id>_ext_<schema_slug>, where <schema_slug> is the manifest slug with every - replaced by _ (Postgres unquoted-identifier safety).
| Manifest slug | Schema slug | Schema name |
|---|---|---|
paperless | paperless | k9o_<proj_id>_ext_paperless |
context | context | k9o_<proj_id>_ext_context |
gate-studio | gate_studio | k9o_<proj_id>_ext_gate_studio |
my-cool-extension | my_cool_extension | k9o_<proj_id>_ext_my_cool_extension |
The plugin token has DDL within this schema only and no DDL anywhere else — a hard guarantee enforced by the underlying Postgres role's privileges, not the application layer.
2.5 Hooks declaration
The hooks object declares which lifecycle events the extension handles. The event keys are a closed set: the lifecycle events enable, configure, activate, deactivate and purge, plus the optional monitor (liveness) and data_export. Each entry carries a url; delivery to the extension is a dispatcher frame to the host function (below), not an HTTP call to that URL.
"hooks": {
"enable": { "url": "POST /hooks/enable" },
"configure": { "url": "POST /hooks/configure" },
"activate": { "url": "POST /hooks/activate" },
"deactivate": { "url": "POST /hooks/deactivate" },
"purge": { "url": "POST /hooks/purge" },
"monitor": { "url": "GET /hooks/monitor" },
"data_export": { "url": "POST /hooks/data_export" }
}
A manifest that declares hooks must also set surfaces.runtime_api.function to the name of the host function that receives them, and that name must match a sandbox entry in background_logic.functions[] (§2.3). Hooks are optional; a missing entry means no delivery (the platform performs the lifecycle action and emits the audit event, but does not invoke the extension). See §4.2 for how hooks are delivered.
2.6 Theming and host compatibility
If your extension contributes a Console iframe, two optional fields let you make it feel native and degrade gracefully when the host's design system moves underneath you. Both are opt-in — omit them and nothing changes.
compatibility declares the minimum host versions your iframe was built against:
| Field | Description |
|---|---|
tokenset_version_min | Minimum host design-token version (semver) your UI expects. |
shadcn_version_min | Minimum Shadcn component-library version (semver) your UI expects. |
At iframe mount, the Console compares the live host versions against your minimums. If the host is older than you require, the Console surfaces a banner to the operator — it never refuses to mount. The point is graceful signalling, not a hard gate: your UI still loads, but the operator is told it was built for a newer host, so a visual glitch reads as "this extension expects a newer Console" rather than "this extension is broken."
custom_tokens declares default values for your own CSS custom properties, so your iframe theme is defined in one place rather than hard-coded across your styles:
"custom_tokens": {
"--ext-forms-accent": "#2563eb",
"--ext-forms-field-radius": "6px"
}
Every key must be namespaced to your slug — the pattern is --ext-<your-slug>-<name> — and the platform enforces it: a token that isn't prefixed with your own slug is rejected at registration with K9O_EXTENSION_CUSTOM_TOKEN_SLUG_MISMATCH. This namespacing guarantees your tokens can never collide with the host's or another extension's.
The Console echoes your declared defaults back to the iframe at init (as customTokensDefaults) so your UI can read them on first paint. What the Console doesn't do is read or interpret your token values, and it doesn't swap them when the operator changes the host theme — your tokens are yours to manage. If you want your iframe to track host theme changes, read the host tokens the Console exposes and derive your own from them; the defaults you declare here are just your starting values.
Both fields default to absent — no version comparison runs, and the echoed customTokensDefaults is an empty object.
2.7 Manifest validation
Manifests are validated at three moments:
- Registration — full schema validation; permissions vocabulary check; reserved-slug check; semver format; surface presence;
static_filesdirectory-name format;surfaces.runtime_apishape validity (prefixformat +specresolves to a valid OpenAPI document whose per-operationpermission_scopecross-references declared permissions);custom_tokensslug-prefix validity (K9O_EXTENSION_CUSTOM_TOKEN_SLUG_MISMATCHon any key not namespaced to the extension's own slug). - Version update — same checks as registration plus a permissions-diff that flags re-authorisation for any addition.
- Enable — re-validates the manifest against the project's current schema (collections may have changed since registration);
K9O_EXTENSION_MANIFEST_INVALIDif a permission references a collection that no longer exists.
2.8 Customer credentials and vendor relationships
Extensions that talk to third-party services — Stripe, Salesforce, ZoomInfo, an LLM provider, a geocoding API, a data warehouse — do not embed credentials. The model is customer-BYO: at install time, the project's operators supply their own API keys, OAuth tokens, or service-account credentials for whatever vendors the extension integrates with. Those credentials are stored in the project's Kibo software-protected secrets store, referenced by the extension at runtime but never returned in plaintext to extension code.
The consequence is structural, not just operational:
- Your keys, your data, your vendor relationships. The customer's credential authenticates the customer to the vendor under the customer's own plan. The platform doesn't proxy, resell, or sub-process the third-party usage — it stays out of the middle of your vendor relationship.
- Credentials live in Vault. The same custody story that protects your project's encryption keys protects your vendor credentials. Rotation is a Vault operation, logged in the audit ledger.
- Vendor billing is between you and the vendor. Your platform bill carries the usage we incurred running the extension (
meta.cost.<dimension>per Billing); the vendor's API charges hit your account with the vendor. - No partner-license dependency. Extensions built against public vendor APIs don't require the platform to hold a commercial relationship with the vendor, and you don't pay a platform-side licensing premium for the connector.
For extension authors, the practical implication is to declare credential requirements in the extension's enable/configure hooks (operators supply credentials at enable time) and reference them through the platform's secrets surface at runtime — never embed, never log, never echo to the extension's outgoing payloads beyond the vendor's own API call.
3. Lifecycle state machine
3.1 Org-level registration
register unregister
unregistered ──────► registered ──────────► unregistered
(30-day grace; §3.5)
Platform-curated extensions are pre-registered in every org's registry; POST /extensions-admin and DELETE /extensions-admin/<slug> on the org subdomain (<orgSlug>.api.k9o.io) register and unregister an extension (ORG_ADMIN+).
3.2 Project-level enable
enable disable
disabled ────────► enabled ──────────► disabled
▲ │
└───────────────────────────────────────┘
(idempotent toggle)
The full state transition table:
| From → To | Endpoint | Auth floor | Side effects |
|---|---|---|---|
(none) → enabled | POST /@<projectSlug>/extensions-admin/<slug>/enable | PROJECT_ADMIN | Per-project plugin token issued; per-project SQL schema provisioned; migrations applied; functions deployed; enable hook fired; permission grants recorded; extension.enabled audit event |
enabled → disabled | DELETE /@<projectSlug>/extensions-admin/<slug>/disable | PROJECT_ADMIN | Plugin token revoked; in-flight hook deliveries cancelled; deactivate hook fired (best-effort); SQL schema retained per default preserve_data: true; functions retired; extension.disabled audit event |
disabled → enabled | POST /@<projectSlug>/extensions-admin/<slug>/enable | PROJECT_ADMIN | Re-issues plugin token; resumes existing schema; functions re-activated; activate hook fired; if the manifest version has changed since the prior enable and adds permissions, returns K9O_EXTENSION_REAUTHORISATION_REQUIRED (409) |
(any) → purged | DELETE /@<projectSlug>/extensions-admin/<slug>/purge | PROJECT_ADMIN + IRREVERSIBLE_ACTION_GATE (EXTENSION_PURGE) | Plugin token revoked; per-project SQL schema dropped; functions hard-deleted; purge hook fired; data is irrecoverably destroyed |
3.3 Extension function lifecycle
Extensions that declare surfaces.background_logic.functions[] deploy and manage functions through the standard Compute function-registry path, with disposition tied to the extension's enable lifecycle:
| Enable lifecycle event | Function disposition |
|---|---|
(none) → enabled (first enable) | Functions deployed; status active; artifact uploaded and registered |
enabled → disabled (preserves config + data) | Functions retired (status retired); not invocable; registry row preserved; artifact retained for re-enable |
disabled → enabled (config + data preserved) | Functions re-activated (status active); name cooldown bypassed; no re-upload needed |
(any) → purged (gated; data destroyed) | Functions hard-deleted; artifact deleted; full hard-delete-on-purge semantics |
The disable vs purge distinction is binding: disable preserves both registry and artifact for a same-identity re-enable, while purge invokes the hard-delete path.
3.4 Permission-grant moments
Permissions are bound at two specific moments:
- Initial enable (
(none) → enabled). The project admin reviews the manifest'spermissions[]array and confirms. The grant is recorded and bound to the extension's manifest version at that instant. - Re-authorisation (
disabled → enabledafter a permission-additive version bump, or explicitPOST /@<projectSlug>/extensions-admin/<slug>/reauthorise). The project admin sees only the additional permissions; confirming records a new grant version.
The grant is keyed on (project_id, extension_id, manifest_version). List the current grant on a project via GET /@<projectSlug>/extensions-admin/<slug>/permissions.
3.5 Registration grace
Unregistration of an extension does not immediately disable the extension on every project. The extension enters a registered_grace state for 30 days during which:
- Existing project enables continue to function.
- No new project enables succeed (
K9O_EXTENSION_UNREGISTERED409). - A subsequent
POST /extensions/<id>/register(on<orgSlug>.api.k9o.io) re-instates the extension cleanly.
After the grace, the extension hard-unregisters; project enables are forcibly disabled; purge hooks fire; per-project data is retained per the project's preserve_data policy.
4. Hook invocation contract
4.1 Hook event types
| Event | Triggered by | Synchronous? |
|---|---|---|
enable | (none) → enabled first-enable | Yes — failure aborts the enable |
configure | Manifest version update with config-relevant changes | Yes — failure aborts the version update |
activate | disabled → enabled re-enable | No — fire-and-forget; failures logged |
deactivate | enabled → disabled disable | No — fire-and-forget; failures logged |
purge | (any) → purged purge | No — fire-and-forget with 30-second grace before plugin token revocation |
| Manifest-declared event hooks | Webhook subscriptions on platform events (document.created, etc.) | Per-hook — see the SIEM forwarding pattern for the parallel delivery mechanics |
4.2 Hook delivery
The platform delivers a hook as a dispatcher frame to the host function the manifest names in surfaces.runtime_api.function. The frame's context.kind is "hook" and context.hookName carries the event: enable, configure, activate, deactivate or purge. The function handles the event in-process and returns its result to the platform; there is no HTTP request to a hook URL.
4.3 Timeout and retry
| Aspect | Value |
|---|---|
| Hook timeout | 30 seconds (enable / configure / activate synchronous) — a timed-out hook aborts the lifecycle action with K9O_EXTENSION_HOOK_TIMEOUT (504) and context.cause |
| Async retry policy | Exponential backoff for deactivate / purge / event hooks — initial 30s, max 15min, for up to 48h. After 48h of delivery failure, hook fires extension.hook_delivery_failed audit event; pauses; resumes when the endpoint is reachable. |
| Delivery semantics | At-least-once for all hooks; the extension must be idempotent on hook invocation |
4.4 Failure semantics
| Hook | On failure |
|---|---|
enable | Enable aborts; per-project schema rollback; plugin token not issued; client sees K9O_EXTENSION_HOOK_DELIVERY_FAILED (502) |
configure | Version update aborts; manifest stays at prior version |
activate | Re-enable proceeds; failure logged + alerted on; subsequent calls retry per §4.3 |
deactivate | Disable proceeds; plugin token still revoked at the scheduled time; failure logged |
purge | Purge proceeds; 30-second grace before plugin token revocation gives the extension a chance to flush any in-flight state; failure logged |
5. Endpoints
5.1 Org-level registration endpoints
POST /extensions-admin — register (ORG_ADMIN+) ┐
GET /extensions-admin — list registered extensions │ on <orgSlug>.api.k9o.io
GET /extensions-admin/<slug> — read a single extension │ (org subdomain; no @<projectSlug>)
PATCH /extensions-admin/<slug> — update the manifest (version bump) │
DELETE /extensions-admin/<slug> — unregister (enters 30-day grace) ┘
5.2 Project-level enable endpoints
POST /@<projectSlug>/extensions-admin/<slug>/enable — enable (or re-enable)
DELETE /@<projectSlug>/extensions-admin/<slug>/disable — disable (preserves data)
DELETE /@<projectSlug>/extensions-admin/<slug>/purge — purge (destroys data; IRREVERSIBLE_ACTION_GATE)
POST /@<projectSlug>/extensions-admin/<slug>/reauthorise — re-authorise after manifest version-bump
GET /@<projectSlug>/extensions-admin — list project extension state
GET /@<projectSlug>/extensions-admin/<slug>/permissions — read the active grant
5.3 Console iframe embedding
Console-side extensions render in a sandboxed iframe whose src is constructed from the user-content host — <label>-cdn-<rgn>.<usercontent-domain>, an opaque per-(project, extension) label under the deployment's configured user-content domain. Extensions declare a top-level static_files directory in the manifest (default "static"); the gateway publishes the directory contents to the user-content host at install time. Iframe bundles relocate to <static_files>/iframe/<surface-name>/ per the bundle-relocation discipline:
<extension-root>/
static/
iframe/
authoring/ ← bundle for the "authoring" surface
preview/ ← bundle for the "preview" surface
When the Console mounts an extension at a /console/extensions/<slug>/* route, the iframe src resolves to:
https://<label>-cdn-<rgn>.<usercontent-domain>/extensions/<slug>/<version>/<iframe_path>
Resolve the URL for an installed extension with GET /@<projectSlug>/extensions-admin/<slug>/iframe-url, which returns { iframeUrl }.
CSP discipline. The Console pins the iframe's Content-Security-Policy to the user-content host (platform-managed, not a manifest-declared origin):
frame-src https://<label>-cdn-<rgn>.<usercontent-domain>;
script-src https://<label>-cdn-<rgn>.<usercontent-domain>;
default-src 'none';
postMessage bridge. The iframe communicates with the Console only via the platform-provided postMessage bridge. The bridge enforces:
- A typed message schema (
{ type, payload }both directions) - Per-message origin validation against the user-content host (
<label>-cdn-<rgn>.<usercontent-domain>) - Token-passing for plugin-token-authorised requests from the iframe back to the API class at
<orgSlug>.api.k9o.io/@<projectSlug>/extensions/<slug>/<path>per §2.3
Direct window.parent.* calls from the iframe are blocked by same-origin policy and the Console's CSP. The extension's iframe runs in an effectively-isolated browser context.
Composition with BYOS custom-domain. When a project has BYOS configured with an optional custom_domain, CDN URLs may route to the customer's brand domain (e.g., iframes accessible at https://cdn.acme-corp.com/@<projectSlug>/extensions/<slug>/iframe/<surface>/... instead of the user-content host); CSP rules update accordingly.
6. Per-project extension surface
6.1 Extension plugin token
Every enabled (project, extension) pair has a plugin token — a short-lived platform JWT with actor: "extension" plus additional claims:
{
"iss": "<this deployment's API origin>",
"aud": "proj_<base62>",
"sub": "ext_<base62>",
"jti": "<uuid>",
"actor": "extension",
"extensionId": "ext_<base62>",
"extensionSlug": "<slug>",
"org_id": "org_<base62>",
"proj_id": "proj_<base62>",
"groups": [ ... ],
"mfa": "<mfa state>",
"manifestVersion": "1.0.0",
"permissions": [ ... ],
"roles": ["extension"],
"scope": [],
"iat": 1746192000,
"exp": 1746195600
}
| Property | Value |
|---|---|
| Access TTL | 1 hour |
| Refresh binding | Bound to the (project, extension) enable lifetime; revoked on disable |
| RBAC role | extension (roles: ["extension"], scope: []; non-human, not in the human role taxonomy) |
6.2 Extension-originating request mechanics
When the extension calls the platform API, the plugin token presents subject.role = "extension" and subject.extensionId = ext_<id>. The gateway runs the standard two-layer access-control check:
- Manifest grant check — does the manifest's
permissions[]authorise the resource + action being requested? - JSON policy evaluation — does the project's JSON policy permit the extension caller? The policy can reference
subject.role = "extension"andsubject.extensionIdfor fine-grained rules.
A permission grant alone is necessary but not sufficient — the project's JSON policy can still deny a specific call. Sovereign customers retain the ability to restrict extensions independently of manifest grants.
6.3 Cross-schema data access
Extensions cannot access data outside their own per-project schema directly. Cross-schema reads and writes go through the gateway API (the same documents / collections / files endpoints the SDK exposes). The extension's plugin token authenticates the call; the manifest grant + JSON policy governs what it can do.
7. See also
- Build Your Own Extension — developer guide for shipping your own extension.
- Paperless — AI-enabled team workspace Trailblazer-class extension.
- Context — semantic-intelligence Trailblazer-class extension.
- Lookout — dashboarding Trailblazer-class extension.
- Gate Studio — visual Gate authoring Trailblazer-class extension.
- API → Security — RBAC enforcement and audit-event family for extension lifecycle.
- API → Control — JSON-policy evaluation layered on the manifest grant.
- API → Compute — function registry that extension
background_logic.functions[]deploys against. - Specs → Error Catalogue — every coined extension-family error code.