Embed your own tool in Clarion's sidebar with signed identity

Most teams have a few tools that don’t belong in Clarion’s core but that people need while they’re in it: an ad-spend dashboard, a capacity planner, a client report. Embedded apps put those tools in Clarion’s sidebar, inside the same window, and tell them who is looking so they can show the right company’s data.

What it looks like

An owner or admin adds an app under Settings → Integrations → Embedded Apps with a name and an https:// URL. It appears under Apps in the sidebar for everyone in the company. Opening it loads the app in an iframe, with its name in a header bar and a button to open it in a new tab.

How your app knows who’s viewing

Your app can’t see Clarion’s session, and it shouldn’t trust anything the browser claims. So Clarion hands it a token:

1. When your page loads, it posts { type: "clarion:ready" } to its parent window.
2. Clarion, which only listens to messages from your app’s exact origin, asks the API to mint a token and replies with { type: "clarion:context", token }.
3. Your page sends the token to your own backend, which verifies it with the app’s signing secret.

The token is an HS256 JWT. Once verified, it tells you:

{
  "iss": "clarion",
  "aud": "<your app's id>",
  "companyId": "clc...",
  "companySlug": "acme",
  "companyName": "Acme Ltd",
  "teamId": null,
  "userId": "clu...",
  "email": "sam@acme.com",
  "name": "Sam Lee",
  "role": "ADMIN",
  "iat": 1759823052,
  "exp": 1759823352
}

Tokens last five minutes, and the aud claim ties each one to a single app, so a token minted for one app is useless to another.

Three layers of protection

Clarion’s Settings page spells out a three-part pattern, and you should use all three:

• Lock framing to Clarion. Send Content-Security-Policy: frame-ancestors https://app.onclarion.com so browsers refuse to embed your app anywhere else.
• Keep the secret server-side. The browser only relays the token; your backend holds the signing secret and does the check.
• Verify every claim. Check the signature, that iss is clarion, that aud is your app’s id, and that exp hasn’t passed. No valid token means the app wasn’t opened from Clarion — show a locked state and stop.

The full code is in Build an embedded app. The same Settings section also has a Copy guide for LLM button that copies the handshake, token shape and all three layers as one prompt, if you’re building the app with an AI assistant.

Reading Clarion data from your app

The identity token says who is viewing; it isn’t an API credential. If your app also needs Clarion data — the company’s metrics, say — call the REST API from your backend with a company API key that has only the scopes it needs. Pair it with webhooks if the app should react to changes.

Only embed what you trust

An embedded app runs inside Clarion’s window and sees who’s viewing it. Only owners and admins can add, remove or reveal the secret for an app — see roles and permissions — and they should only add apps they control or trust.

For the reasoning behind each step, read Embed your tool in Clarion.