埋め込みリンク

エージェントのプレビューや外部サービスへの埋め込みに使う、短期間かつブランド表示のないリンクを作成します。

埋め込みリンクを使うと、Busabase のセッションやワークスペース内のほかの情報を公開せずに、エージェントの作業結果を表示できます。たとえば、Buda や Codex が MCP 経由で Base や Doc を更新した後、一時リンクを作成して完成した内容をサイドパネルで開けます。別のアプリケーションは、同じ capability を iframe での埋め込みにも利用できます。

埋め込みページに表示されるのはノードの業務コンテンツだけです。Busabase のダッシュボード、トップバー、ノードヘッダー、ロゴ、製品ブランドは表示されません。一方、データそのものは匿名化も書き換えもされません。ノードに保存された名前、レコード、ファイル、リンクなどはそのまま表示されます。

利用条件

埋め込みリンクを管理するには、次の条件が必要です。

manage レベルの API キー、または 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"]
    }
  }'

作成に成功すると、メタデータと 2 種類の 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 へリダイレクトします。
別の Web サイトまたは WebView に埋め込む	`iframeUrl`	最初のドキュメント要求で capability を直接検証するため、サードパーティ Cookie を必要としません。

外部サイトの iframe では iframeUrl を直接使用してください。

<iframe
  src="https://your-busabase.example/embed/emb_example?token=...&view=iframe"
  referrerpolicy="no-referrer"
  title="リリースダッシュボード"
></iframe>

先に url を開き、リダイレクト後の token を含まない URL を iframe にコピーしないでください。その URL はトップレベルブラウザーの Cookie に依存しており、クロスサイト埋め込み用ではありません。

埋め込み元を制限する

framePolicy は、ブラウザーが強制する iframe ポリシーを制御します。

モード	使用場面
`anywhere`	どのサイトからでも埋め込みを許可します。`framePolicy` を省略した場合のデフォルトです。
`origins`	`allowedOrigins` に指定した正確な HTTPS Origin だけを許可します。ホストアプリケーションが分かっている場合に推奨します。
`top-level-only`	直接開くことだけを許可し、iframe への埋め込みを禁止します。

Origin には https://agent.example のような正確な Origin を指定します。パス、クエリ文字列、認証情報、ワイルドカードは使用できません。最大 20 個まで指定でき、通常の 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 の範囲内で埋め込み内容を読めます。ログや分析システムに記録したり、チケットやプロンプトへ貼り付けたり、再共有したりしないでください。
埋め込みレスポンスには no-store と no-referrer が設定されます。サードパーティ Cookie が無効でも動作できるように、iframe フローでは意図的に capability を URL に残します。

関連: REST API · MCP 連携 · OpenAPI リファレンス