Administration

Two roles are involved in getting an app to users:

• A global admin manages sources for the whole platform: registers them, syncs them, and grants them to organizations.
• An organization admin decides who in their organization can use each app, and approves the scopes and network origins it asks for.

Global admin is a platform-level role, separate from organization roles. On a self-hosted installation the operator designates the first global admin when deploying the identity service (BOOTSTRAP_ADMIN_EMAIL).

Register a source

As a global admin, open Settings → Global → App sources and choose Add source.

Test connection checks the settings without saving and reports how many manifests it sees under the prefix. Create source saves the source; it does not sync it.

See Publishing for the bucket layout and the limits that apply.

Sync it

A new source shows Never synced. Open the source's ⋮ menu and choose Sync now. The result is reported as a notification:

• Synced n app(s). — everything under the prefix was valid.
• Synced n app(s); m skipped as invalid. — some manifests failed validation. The interface does not say which or why; ask the app's developer to check the manifest.

Sync again whenever a developer has uploaded a change — S3 sources are never synced automatically. The same menu offers Test connection and Delete. Deleting a source removes all of its apps from the platform.

Grant it to organizations

A synced source is hidden from every organization. Choose Manage access on the source, then Add next to each organization that should receive its apps.

For every app you can pin the version an organization runs: Latest follows each sync, a specific version stays fixed until you change it. Removing an organization revokes its access to all apps of the source.

Availability and consent

Once a source is granted, its apps appear for the organization's admins under Marketplace → Apps, marked Not available. The organization admin opens the app's Manage availability control to decide who can use it:

• Only chosen people — hidden from the organization; granted to selected users. This is the default.
• Available to install — members see the app and can install it themselves.
• Installed for everyone — installed for the whole organization.
• Public — usable by anyone, without installing.

The same panel is where the admin approves scopes beyond workspace:own and store:own (for example documents:read or responses:run) and the connectOrigins the app wants to reach. Until a requested scope or origin is approved, calls that need it are rejected.

Installed apps open from Marketplace → Apps → Open, at /apps/<slug>.

REST API access

If the app's manifest lists apiScopes, its Manage availability panel has a REST API access section with one switch per requested scope. An approved scope lets the app call the HUB.KI REST API as the person using it — never beyond what that person may see themselves. Scopes that change data or act for the person (every *:write scope, connectors:invoke, connectors:approve and the organization-wide tracing:read and tracing_content:read) carry a Sensitive badge. Approve only what the app needs.

You can approve tracing:read and tracing_content:read without being able to view tracing yourself. The approval only lets the app ask for the scope: the app reads the organization's tracing only for people who hold the View traces permission (part of the built-in Admin role), and gets a refusal for everyone else. tracing:read covers the trace ledger only; the conversations of chats shared for debugging need tracing_content:read, so approve it only for apps that have to read them.

When you switch an app that requests scopes to Available to install or Installed for everyone, a consent dialog lists the same scopes, REST API scopes included, and asks you to approve them before the change is saved.

Withdrawing a REST API scope, removing a person's access to the app, or making the app unavailable takes effect on the app's next REST API request, including requests with tokens it was issued earlier. Files and jobs the app created through the REST API are kept: the app can reach them again once you approve the scopes again, and work it started before the withdrawal finishes. Revoking the app's source from your organization or deleting the source removes the approval itself.

Approving responses:run or any REST API scope issues the app an API key for your organization. It is listed under Settings → Organization settings → API Keys, marked Custom app, and is managed through the app's approval rather than edited directly. It is revoked when you withdraw every scope that needed it.