Build an app

Developers can build custom apps for SweetHive - a small data view embedded in a context, or a full product on its own URL. You register the app once, receive client credentials, and build against the App SDK.

Two kinds of app

Both authenticate the same way: a short-lived scoped token, bounded server-side by the install's scope and the viewer's live visibility. Your app never sees more than the person using it can see, and access is revoked the instant they lose it.

Most products combine both: a hub app (the External console at hub.sweethive.com) plus one or more app widgets - the Embedded view shown inside a context. In the app's own settings you pick which contexts of the hive display the widget, so the same app is both a place to run the workflow and a panel that lives inside the relevant contexts.

Register and build

1. Open Developer → Apps from the user menu.
2. Choose Register app: name it, pick Embedded or External, set the URL, icon and capability.
3. Save the client ID and secret (shown once).
4. Download the SDK dev guide (.md) - the complete contract: the iframe handshake, auth, the scoped data API, testing and publishing. Drop it into your repo and build with your AI coding assistant. Also available here: SWEETHIVE_APP_SDK.md.
5. Set the app to Active so hive admins can install it from Context → Apps → Add app.

How the standard works

• Embedded apps run in a sandboxed iframe and receive a short-lived scoped token via a postMessage handshake - never a cookie, so it also works in the mobile apps. Your app must allow SweetHive to frame it (a frame-ancestors CSP that includes the mobile app origins - the SDK guide gives the exact header).
• External apps open at their own URL with a signed launch; on mobile they open in the native in-app browser.
• Every data call is bounded server-side by the install scope intersected with the viewer's live visibility - same law, same audit as any SweetHive actor.

External apps and hubs

An external app is a full product on its own URL. SweetHive shows a launch tile; on click the app opens with a signed launch and starts its own session - on mobile in the native in-app browser.

External apps on an allowlisted origin can also sign users in directly with their SweetHive account (SSO): with a live SweetHive session there is no password prompt; otherwise the user signs in on the SweetHive login page and is bounced straight back into the app. Request the allowlisting when you register the app.

Multi-hive hubs: one shell, many apps

A product that manages several hives from one UI follows the hub shell standard - one reusable shell shaped by a manifest:

• The shell provides, once for every app: SSO sign-in, the top-right hive selector, Team and Invitations management, light/dark theme and the collapsible sidebar.
• The manifest (stored with the app registration) declares the brand and the left-panel entries. Each entry opens a view built into the shell or - the key part - any embedded SweetHive app rendered in a frame, unchanged: one build serves the context UI and the hub.
• Switching hive re-scopes everything: the shell resolves the app's install in the selected hive and reloads the active view, so every screen follows the hive - including empty states for hives where the app isn't installed.

The SDK guide has the full contract: the manifest schema, the view handshake and the pitfalls.

Test and publish

Register your app with a localhost URL, install it into a test context, and the handshake delivers a real scoped token against your data. When it's ready, set it Active - and disable it anytime; installs stop immediately.

App settings

An installed app can carry per-install settings - small configuration a hive admin sets (a linked resource, an integration key, a mode). They are stored with the install and delivered in the launch payload; the app reads them at startup and again when the admin changes them, no redeploy. Use this for configuration. Your app's domain data (its records) belongs in your own store, keyed by the install or its context - SweetHive gives identity, scope and people/groups; your app owns its data.

Roles & permissions

A role is a named set of your app's features, assigned to groups - never to individual people: members inherit it through their group. Groups and people come from SweetHive, listed for the context the app is installed in (your app reads them). Roles are your app's data - create them in your own store, then assign each to the right groups (search the install context's groups for large hives). Two steps in order: create the role (name + features), then assign it to groups.

Connect apps to each other

Apps don't call each other directly - they connect through the SweetHive connectors layer. One app emits an event (say, "a lead was captured") and a per-hive connector routes it to another app's action (say, "record marketing attribution"). Turning an integration on or off is a setting, not code in either app, so the two apps stay independent.

• Register once what your app emits and what it accepts (its actions).
• Wire a connector for a hive: source app + event to target app + action. An admin manages these from the Connectors page; enable, disable or remove them at any time.
• Delivery is best-effort: if the other app is down, your app's own flow is never affected, and every delivery is logged so an admin can see what happened.

An optional field mapping lets any event feed any action even when the field names differ, so new integrations are pure configuration. The SDK guide has the event/action contract and the exact endpoints.