Skip to main content

UI plugins

Extend the web app with new surfaces.

What you'll learn​

  • Plugin manifest
  • Available surfaces
  • Auth handshake (iframe vs. new tab)

Manifest​

{
"name": "my-ui-plugin",
"type": "ui-plugin",
"surfaces": ["sidebar-bottom", "workspace-settings"],
"entryUrl": "https://my-plugin.example.com/embed.html",
"icon": "https://my-plugin.example.com/icon.svg",
"requiredPermissions": ["read:files"]
}

Register via Developer Console → UI Plugins → New or via GraphQL mutation.

Surfaces​

SurfaceWhere it appears
sidebar-top / sidebar-bottomWorkspace sidebar
workspace-settingsWorkspace settings tabs
project-toolbarPer-project action bar
global-commandCommand palette (Cmd+K)

Auth handshake (iframe)​

The web app embeds your URL in an iframe and posts a token via postMessage:

window.addEventListener('message', (e) => {
if (e.origin !== 'https://app.burdenoff.com') return;
if (e.data.type === 'burdenoff:auth') {
const { token, workspaceId, userId } = e.data;
// Use token for API calls
}
});

Auth handshake (new tab)​

If entryUrl opens in a new tab, the app passes ?bo_token=...&bo_workspace=... as URL query. Strip them after read.

Next steps​