埋め込みリンク

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

埋め込みリンクを使うと、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 は転送されず、書き込みはすべて拒否されます。

対象の種類と権限

埋め込みリンクは常に type と typeId の組み合わせで対象を指定します。type の値は次のいずれかです。

`type`	`typeId` の意味	`manage` 権限の確認対象
`node`	ノード自身の ID。	そのノード自体。
`change-request`	変更リクエスト（change request）の ID。	その変更リクエストが属するノード。
`record-detail`	レコードの ID。	そのレコードが属する Base のノード。

いずれの場合も、権限チェックは最終的に単一の所属ノードに帰着し、そのノードに対する manage 権限が必要です。変更リクエストやレコードに個別の ACL パスはなく、属するノード（または Base のノード）の権限を引き継ぎます。

リンク管理は作成者だけに限定されず、現在の権限に基づきます。選択したスペース内で、所属ノードに対する manage 権限を現在持つ呼び出し元であれば、リンクを一覧取得または取り消しできます。その権限を失うと、一覧にリンクは表示されず、取り消しもできません。

レスポンスの targetName は、type が node の場合はノード名、それ以外の場合は変更リクエストまたはレコード自身の ID です。nodeType（例: base、doc、airapp）は type が node の場合にのみ設定され、change-request と record-detail では常に null になります。

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

作成に成功すると、メタデータと 2 種類の capability URL が返ります。

{
  "id": "emb_example",
  "type": "node",
  "typeId": "nod_example",
  "targetName": "リリースダッシュボード",
  "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"
}

ノード全体ではなく、レビュー中の変更リクエストや単一レコードの詳細ビューを埋め込みたい場合は、type を change-request または record-detail に設定し、その対象自身の ID を typeId に指定します。リクエストとレスポンスの形式は同一で、変わるのは上記で説明した targetName と nodeType だけです。

シークレットは作成レスポンスでのみ返されます。後からリンクを一覧取得しても、どちらの 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 での開発時にだけ許可されます。

直接表示専用のリンクを作成する例です。

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

リンクの一覧取得と取り消し

管理できるすべてのリンクを取得します。?type=node&typeId=nod_example を追加すると絞り込めます（どちらも省略可能・独立したパラメーターです。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"

一覧には active、有効期限、取り消し状態、frame policy などのメタデータが含まれますが、bearer secret、url、iframeUrl は返りません。

対象の所属ノードに対する manage 権限を現在持つ呼び出し元であれば、リンクを直ちに取り消せます。

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 上の作業を完了し、埋め込む対象の最終的な type（node、change-request、record-detail のいずれか）と typeId を特定します。
ユーザーがプレビューまたは共有を求めた場合に限り、embed_links_create を呼び出します。type、typeId と、必要に応じて expiresInMinutes、framePolicy、targetSpaceId を渡します。
ブラウザーのサイドパネルでは url を開き、外部システムの iframe には iframeUrl を渡します。
embed_links_list で現在および過去のメタデータを確認し、ユーザーがアクセス停止を求めたら embed_links_revoke を呼び出します。

MCP ツールは同じ契約を使用し、追加でスペース選択用の任意引数を受け取ります。

ツール	必須引数	任意引数
`embed_links_create`	`type`、`typeId`	`expiresInMinutes`、`framePolicy`、`targetSpaceId`
`embed_links_list`	—	`type`、`typeId`、`targetSpaceId`
`embed_links_revoke`	`id`	`targetSpaceId`

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 リファレンス

埋め込みリンク

On this page