嵌入链接

嵌入链接让智能体展示工作结果，而无需暴露 Busabase 会话或工作空间的其他内容。例如，Buda 或 Codex 通过 MCP 更新 Base 或 Doc 后，可以创建一个临时链接，在侧边面板中打开最终内容。其他应用也可以使用同一个 capability，通过 iframe 嵌入内容。

嵌入页面只渲染节点的业务内容，没有 Busabase Dashboard、Topbar、节点页头、Logo 或产品品牌。业务数据本身不会被匿名化或改写：节点中保存的名称、记录、文件、链接等内容仍会原样显示。

开始之前

管理嵌入链接需要：

manage 级别的 API Key，或已通过 OAuth 连接的 MCP 客户端；
对目标节点拥有 manage 权限；
用户明确要求预览或分享该节点。

当前支持 Base、Doc、File、Drive、Skill、Folder 和 AirApp。AirApp 链接会在浏览器端 Nodepod 中启动节点当前已合并的文件，并且只显示应用内容。应用调用 Busabase SDK 时使用短期 Embed capability 和明确的只读过程白名单；不会转发访问者 Session、OAuth Token 或 API Key，所有写入都会被拒绝。

通过 REST 创建链接

创建一个有效期 15 分钟、只允许你的应用嵌入的链接：

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"]
    }
  }'

创建成功后会返回元数据和两个 capability URL：

{
  "id": "emb_example",
  "nodeId": "nod_example",
  "nodeName": "发布数据看板",
  "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"
}

密钥只会随创建响应返回。之后列出链接时，不会再次返回任何 capability URL。

选择正确的 URL

用途	URL	行为
在浏览器或智能体侧边面板中打开	`url`	将 capability 换成 HttpOnly Cookie，然后重定向到不含 token 的干净 URL。
嵌入其他网站或 WebView	`iframeUrl`	在首次文档请求中直接验证 capability，不依赖第三方 Cookie。

第三方 iframe 应直接使用 iframeUrl：

<iframe
  src="https://your-busabase.example/embed/emb_example?token=...&view=iframe"
  referrerpolicy="no-referrer"
  title="发布数据看板"
></iframe>

不要先打开 url，再把重定向后的干净地址复制进 iframe。该地址依赖顶层浏览器 Cookie，不是跨站嵌入地址。

控制允许嵌入的网站

framePolicy 控制由浏览器强制执行的 iframe 策略：

模式	适用场景
`anywhere`	允许任何网站嵌入。省略 `framePolicy` 时默认使用此模式。
`origins`	只允许 `allowedOrigins` 中列出的精确 HTTPS Origin。已知宿主应用时推荐使用。
`top-level-only`	只允许直接打开，禁止放入 iframe。

Origin 必须是 https://agent.example 这样的精确来源。路径、查询参数、登录信息和通配符都会被拒绝。最多可配置 20 个 Origin；普通 HTTP 只允许用于 localhost 开发环境。

创建一个只能直接打开的链接：

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

列出与撤销链接

列出你有权管理的所有链接；也可以添加 ?nodeId=nod_example 按节点筛选：

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"

列表会返回 active、过期时间、撤销状态和 frame policy 等元数据，但绝不会返回 bearer secret、url 或 iframeUrl。

拥有管理权限的所有者可以立即撤销链接：

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"

响应为 { "revoked": true }。之后对两个 capability URL 的访问都会立即停止。

通过 MCP 使用嵌入链接

Buda、Codex 或其他 MCP 客户端通过 OAuth 连接 Busabase 后：

调用 auth_verify。如果用户属于多个空间，先询问要操作哪个空间。
完成用户要求的 Busabase 操作，并确定最终节点 ID。
只有在用户要求预览或分享时，才调用 embed_links_create，传入 nodeId，以及可选的 expiresInMinutes、framePolicy；需要时还要传入 targetSpaceId。
在浏览器侧边面板中打开 url；如果由其他系统的 iframe 承载，则把 iframeUrl 交给宿主应用。
使用 embed_links_list 检查当前和历史元数据；用户要求停止访问时，调用 embed_links_revoke。

MCP 工具名为：

embed_links_create
embed_links_list
embed_links_revoke

MCP 与 REST 使用相同的权限、有效期、响应结构和安全模型。

过期与安全

链接默认有效 15 分钟，可设置为 1 分钟到最长 24 小时（1440 分钟）。
链接过期后立即无法访问，但不会自动从数据库物理删除。为便于所有权管理和审计，列表仍可能保留该元数据，并显示 active: false。
撤销同样会立即阻止后续访问，但无法收回接收方已经下载或截图的内容。
两个 URL 都包含 bearer capability。任何拿到有效 URL 的人，都能在 frame policy 允许的范围内读取嵌入内容。不要把它写入日志或分析系统，也不要粘贴到工单、Prompt 中或二次分享。
嵌入响应使用 no-store 和 no-referrer。为了在第三方 Cookie 被禁用时仍能工作，iframe 流程会有意把 capability 保留在 URL 中。

另请参阅：REST API · MCP 集成 · OpenAPI 参考