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 node'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 stored in the node 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; and
• an explicit request from the user to preview or share that node.

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.

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 '{
    "nodeId": "nod_example",
    "expiresInMinutes": 15,
    "framePolicy": {
      "mode": "origins",
      "allowedOrigins": ["https://agent.example"]
    }
  }'

A successful response includes metadata plus two capability URLs:

{
  "id": "emb_example",
  "nodeId": "nod_example",
  "nodeName": "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"
}

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:

{
  "nodeId": "nod_example",
  "framePolicy": { "mode": "top-level-only" }
}

List and revoke links

List every link you can manage, or add ?nodeId=nod_example to filter by node:

curl "https://your-busabase.example/api/v1/embed-links?nodeId=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.

The managing owner 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 node ID.
3. Only when the user asks to preview or share it, call embed_links_create with nodeId, 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 tool names are:

• embed_links_create
• embed_links_list
• embed_links_revoke

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