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
| Surface | Where it appears |
|---|---|
sidebar-top / sidebar-bottom | Workspace sidebar |
workspace-settings | Workspace settings tabs |
project-toolbar | Per-project action bar |
global-command | Command 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.