Embed Links

Embed Links let an agent show the result of its work without exposing a Busabase session or the rest of the workspace. For example, after Buda or Codex updates a Base or Doc through MCP, it can create a temporary link and open the finished content in a side panel. Another application can use the same capability to embed the content in an iframe.

An embed renders only the target's business content. It has no Busabase dashboard, top bar, node header, logo, or product branding. The data itself is not anonymized or rewritten: names, records, files, links, and other content associated with the target remain visible.

Before you start

Embed Link management requires:

• a manage-level API key or an OAuth-connected MCP client;
• manage permission on the node that owns the target (see Target types and permissions below); and
• an explicit request from the user to preview or share that target.

Supported node types are Base, Doc, File, Drive, Skill, Folder, and AirApp. An AirApp link starts the node's current merged files in browser-side Nodepod and shows only the app viewport. Its Busabase SDK calls use the short-lived Embed capability through an explicit read-only procedure allowlist; no viewer session, OAuth token, or API key is forwarded, and writes are rejected.

Target types and permissions

Every embed link targets exactly one polymorphic pair: type plus typeId. type is one of:

In every case the check resolves to a single owning node and requires manage on it — there is no separate ACL path for change requests or records; they inherit the permission of the node (or the node of the Base) they belong to.

Link management is permission-based, not creator-only. Within the selected space, any caller who currently has manage on the resolved owning node can list or revoke the link. A caller who no longer has that permission does not see the link in list results and cannot revoke it.

The response's targetName is the node's name when type is node, or the change request/record ID otherwise. nodeType (e.g. base, doc, airapp) is populated only when type is node; for change-request and record-detail targets nodeType is always null.

Create a link with REST

Create a 15-minute link that can be embedded only by your application:

curl -X POST "https://your-busabase.example/api/v1/embed-links" \
  -H "Authorization: Bearer $BUSABASE_API_KEY" \
  -H "x-busabase-space: $BUSABASE_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "node",
    "typeId": "nod_example",
    "expiresInMinutes": 15,
    "framePolicy": {
      "mode": "origins",
      "allowedOrigins": ["https://agent.example"]
    }
  }'

A successful response includes metadata plus two capability URLs:

{
  "id": "emb_example",
  "type": "node",
  "typeId": "nod_example",
  "targetName": "Launch dashboard",
  "nodeType": "base",
  "createdAt": "2026-07-21T08:00:00.000Z",
  "expiresAt": "2026-07-21T08:15:00.000Z",
  "revokedAt": null,
  "active": true,
  "framePolicy": {
    "mode": "origins",
    "allowedOrigins": ["https://agent.example"]
  },
  "url": "https://your-busabase.example/embed/emb_example?token=...",
  "iframeUrl": "https://your-busabase.example/embed/emb_example?token=...&view=iframe"
}

To embed a change request under review or a single record's detail view instead of a whole node, set type to change-request or record-detail and pass that object's own ID as typeId. The request and response shapes are identical; only targetName and nodeType change as described above.

The secret is returned only as part of the create response. Listing links later does not return either capability URL.

Choose the correct URL

Use iframeUrl directly as the iframe source:

<iframe
  src="https://your-busabase.example/embed/emb_example?token=...&view=iframe"
  referrerpolicy="no-referrer"
  title="Launch dashboard"
></iframe>

Do not open url first and copy the redirected clean address into an iframe. That address relies on the top-level browser cookie and is not the cross-site embed URL.

Control where framing is allowed

framePolicy controls the response's browser-enforced frame policy:

Origins must be exact origins such as https://agent.example. Paths, query strings, credentials, and wildcards are rejected. Up to 20 origins may be supplied. Plain HTTP is accepted only for localhost development.

For a direct-view-only link:

{
  "type": "node",
  "typeId": "nod_example",
  "framePolicy": { "mode": "top-level-only" }
}

List and revoke links

List every link you can manage, or filter with ?type=node&typeId=nod_example (both are optional and independent — pass type alone to list every embed of that target type):

curl "https://your-busabase.example/api/v1/embed-links?type=node&typeId=nod_example" \
  -H "Authorization: Bearer $BUSABASE_API_KEY" \
  -H "x-busabase-space: $BUSABASE_SPACE_ID"

The list includes active, expiry, revocation, and frame-policy metadata, but never returns the bearer secret, url, or iframeUrl.

Any caller who currently has manage permission on the target's owning node can revoke a link immediately:

curl -X DELETE "https://your-busabase.example/api/v1/embed-links/emb_example" \
  -H "Authorization: Bearer $BUSABASE_API_KEY" \
  -H "x-busabase-space: $BUSABASE_SPACE_ID"

The response is { "revoked": true }. Future requests to either capability URL stop resolving at once.

Use Embed Links through MCP

After OAuth connects Buda, Codex, or another MCP client to Busabase:

1. Call auth_verify. If the user belongs to multiple spaces, ask which space to use.
2. Perform the requested Busabase work and identify the final type (node, change-request, or record-detail) and typeId to embed.
3. Only when the user asks to preview or share it, call embed_links_create with type, typeId, optional expiresInMinutes, optional framePolicy, and targetSpaceId when needed.
4. Open url in a browser side panel, or give the host application iframeUrl for a third-party iframe.
5. Use embed_links_list to inspect active and historical metadata, and embed_links_revoke when the user asks to stop access.

The MCP tools expose the same contract plus the optional space selector:

MCP follows the same permissions, expiry rules, response shapes, and security model as REST.

Expiry and security

• Links last 15 minutes by default and may be set from 1 minute up to 24 hours (1440 minutes).
• Expired links become inaccessible immediately. Expiry does not automatically physically delete the database metadata; list results may retain it with active: false for ownership and audit purposes.
• Revocation also stops future access immediately. It cannot erase content that a recipient already downloaded or captured.
• Both URLs contain a bearer capability. Anyone who has an active URL can read the embedded content within its frame policy. Do not log it, place it in analytics, paste it into tickets or prompts, or share it again.
• Embed responses use no-store and no-referrer. The iframe flow intentionally keeps the capability in its URL so it can work when third-party cookies are blocked.

See also: REST API · MCP Integration · OpenAPI Reference