埋め込みリンク

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

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

利用条件

API キーまたは OAuth 接続済みの MCP クライアントを使用し、対象に応じた権限を満たしてください。

• 単一レコードは write、変更リクエストは changeRequest、ノード全体は manage
• 対象が属するノードに対する対応する権限（詳しくは下記の対象の種類と権限を参照）
• その対象のプレビューまたは共有を求める、ユーザーからの明示的な依頼

対応するノードタイプは Base、Doc、File、Drive、Skill、Folder、AirApp です。AirApp リンクは、ノードの現在マージ済みファイルをブラウザー側の Nodepod で起動し、アプリ本体だけを表示します。Busabase SDK の呼び出しには、短期間の Embed capability と明示的な読み取り専用プロシージャの許可リストを使用します。閲覧者の Session、OAuth token、API key は転送されず、書き込みはすべて拒否されます。

対象の種類と権限

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

API キー自体も対象に必要なレベルを満たす必要があります。通常のメンバーでも、対象 Base に書き込めれば write キーで単一レコードのリンクを作成できます。読み取り権限だけでは作成できません。Cloud でノード全体のリンクを作成したり、リンクを一覧取得・取り消したりするには、引き続きワークスペースの manage と所属ノードの manage が必要です。

リンク管理は作成者だけに限定されず、現在の権限に基づきます。選択したスペース内で、所属ノードに対する 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 も返りません。

write キーで単一レコードを共有する

レコードの作成とマージが完了したら、レコード ID を使って読み取り専用リンクを作成します。

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

この capability は対象レコードと表示に必要な Base メタデータだけを許可し、Base のレコード一覧やほかのレコードは取得できません。返された url を開くと、サインインせずにそのレコードを閲覧できます。リンクは既定で 15 分後に失効し、Base 全体は公開されません。表示されるのは現在のレコードで、有効期間中の更新も反映されます。write キーではリンクの一覧取得や取り消しはできません。早期の取り消しは管理者に依頼してください。

URL の使い分け

外部サイトの 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 ポリシーを制御します。

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 に接続した後は、次の手順で利用します。

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

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

MCP と REST では、同じ権限、有効期間、レスポンス形式、セキュリティモデルが使われます。

有効期限とセキュリティ

• リンクの有効期間はデフォルトで 15 分、1 分から最大 7 日（10080 分）まで設定できます。たとえば expiresInMinutes: 7200 は 5 日です。Busabase skill は通常のチャット結果に 24 時間を明示的に指定し、ユーザーが別の期間を指定した場合はその値を使用します。
• 24 時間を超える指定には、7 日上限の契約を含むサーバーと CLI/SDK が必要です。古いデプロイやインストール済みクライアントでは拒否される場合があるため、サーバーの更新とクライアントの再ビルドまたは更新を行ってください。busabase-cli schema embedLinks.create でインストール済みクライアントの範囲を確認できます。既存リンクの期限は変わらず、返却された expiresAt を表示します。
• 期限切れのリンクには直ちにアクセスできなくなります。ただし、データベース上のメタデータは自動的に物理削除されません。所有権管理や監査のため、一覧に active: false として残る場合があります。
• 取り消しも将来のアクセスを直ちに停止しますが、受信者がすでにダウンロードまたは保存した内容までは回収できません。
• どちらの URL にも bearer capability が含まれます。有効な URL を知っている人は、frame policy の範囲内で埋め込み内容を読めます。ログや分析システムに記録したり、チケットやプロンプトへ貼り付けたり、再共有したりしないでください。
• 埋め込みレスポンスには no-store と no-referrer が設定されます。サードパーティ Cookie が無効でも動作できるように、iframe フローでは意図的に capability を URL に残します。

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