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

Use an API key or an OAuth-connected MCP client with the permission required for your target:

• write for a single record, changeRequest for a proposal, or manage for a whole node;
• the corresponding permission on the target's owning node (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:

API keys must also meet the target's required level. A write key can create a single-record link, including for an ordinary member who can write to that Base. Reading a record alone is insufficient. Creating whole-node links, listing links, and revoking links still require workspace manage in Cloud, plus manage on the owning node.

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.

Share one record with a write key

After the record has been created and merged, use its record ID to create a read-only link:

curl -X POST "https://your-busabase.example/api/v1/embed-links" \
  -H "Authorization: Bearer $BUSABASE_WRITE_API_KEY" \
  -H "x-busabase-space: $BUSABASE_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"type":"record-detail","typeId":"rec_example","expiresInMinutes":15}'

The capability permits that record and the Base metadata needed to display it; it does not permit listing the Base or reading other records. Open the returned url to view that record without signing in. The link expires after 15 minutes by default and does not make the Base public. The viewer sees the current record, including later updates while the link remains active. A write key cannot list or revoke links; ask a manager to revoke one early.

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 7 days (10080 minutes). For example, use expiresInMinutes: 7200 for five days. The Busabase skill explicitly requests 24 hours for ordinary chat results unless another duration is requested.
• Durations above 24 hours require a server and CLI/SDK with the seven-day contract. Older deployments or installed clients may still reject them; deploy the updated server and rebuild or update the client. Check busabase-cli schema embedLinks.create for the installed client's bounds. Existing links keep their original expiry; always display the returned expiresAt.
• 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