BYOK ── Bring Your Own Key

BYOK は、Sonzai のチャット／セッション／抽出スタックをそのまま 利用しながら、裏側のプロバイダ呼び出しを 自社の API キー に 通すための仕組みです。トークン課金は自社のプロバイダ請求に乗り、 それ以外（メモリ、人格、後処理モデル、Sonzai プラットフォームの 請求）はこれまで通り動作します。

Custom LLM (BYOM) とは別物です。 BYOK は Sonzai が直結している既存のプロバイダ統合に、自社の課金キー だけを差し込みます。BYOM はチャット補完エンドポイント自体を 自分でホストしている別のエンドポイント に丸ごと置き換えます。

スコープ

BYOK キーは (プロジェクト × プロバイダ) 単位で保存されます。 1 プロジェクト 1 プロバイダにつきキーは 1 本だけで、エージェント 単位／セッション単位／呼び出し単位の BYOK キーはありません。 モデルの理解は単純です ── あるプロジェクトのチャット ターンが あるプロバイダに着地した場合、そのプロジェクトの該当プロバイダ用 BYOK キー経由で呼び出されます（どのエージェント・どのセッションが 発火源かに依りません）。

同じプロジェクト内で エージェント別に違うキーを使い分けたい 場合、 プロジェクトを分けてください ── 調整できるノブはこれだけです。

セットアップ経路

ワイヤ上は等価な 2 通りがあります。

1. ダッシュボード

単発のセットアップやローテーションには最速。

1. platform.sonz.ai を開き、対象プロジェクトを選びます。
2. Settings → BYOK を開きます。
3. サポート対象の 4 プロバイダごとにカードが並びます。設定したい プロバイダのカードを開きます。
4. プロバイダ（OpenAI、Google AI Studio for Gemini、xAI コンソール、 OpenRouter ダッシュボード）の API キーを貼り付けます。
5. Save を押します。API と同じ同期プローブが走り、上流が キーを拒否した場合は保存自体が失敗してプロバイダのエラー メッセージがそのまま表示されます。不正キーは決して永続化 されません。
6. 保存後はカードが「設定済み」状態に切り替わります ── 冒頭数文字 のプレフィックス、ヘルス バッジ（healthy / unhealthy / unknown）、そして Replace / Test / Disable / Delete の ボタンが並びます。

ダッシュボードは SDK が叩くのと同じエンドポイントを呼んでいるので、 ここでできることは全部スクリプト化できます。

2. API / SDK

IaC、新規テナントの CI ブートストラップ、キー ローテーションの cron、自動テナント オンボーディング中のプロビジョニングなど。 エンドポイントは下に列挙します。

載せられるプロバイダ

プラットフォームがネイティブで話す 4 つです。

• openai
• gemini
• xai
• openrouter（内部フォールバック経路 ── ここにキーを置くと、 プラットフォームが OpenRouter に落ちた時の呼び出しもカバー）

custom の BYOM エンドポイントは BYOK プロバイダではありません。 Custom LLM で設定してください。

保管とセキュリティ

• キーは 保存時に暗号化 され、復号はプラットフォームの リクエスト パス内でのみ。API レスポンスでキー本体が返ることは ありません ── List / Get は api_key_prefix（先頭数文字）だけを 返すので、どのキーがどれかは識別できます。
• 書き込み時に 同期プローブ が走ります。Sonzai が上流に no-op 呼び出しを投げ、不正なキーは PUT が 400 で失敗します。 設定ミスは初回ユーザ チャットではなく セットアップ時点で 浮上 します。
• キーごとに ヘルス情報を追跡 します。読み取りのたびに health_status、last_health_error、last_health_check_at を 返すので、ローテーションされた／無効化されたキーをユーザより 先に検知できます ── 監視に流して、チャット トラフィックが 失敗し始める前にアラートを上げてください。

エンドポイント

プロジェクト単位、(project_id, provider) で索引されます。一覧、 セット、無効化、削除、再テスト ── これだけです。

リクエスト／レスポンスの完全な形は リファレンス → API → BYOK を参照。

プロジェクト API キーのスコープ

ダッシュボードまたは POST /api/v1/projects/{project_id}/api-keys で作成した プロジェクト API キーは scopes 配列を持ちます。SDK 経由で BYOK をプログラム的に 操作するには、以下のスコープが必要です。

• read:byok — プロバイダの一覧確認とヘルス状態の取得。
• write:byok — キーの登録／無効化／削除／再テスト。

テナント レベルの認証情報（Clerk ダッシュボード セッション、["*"] を持つ デフォルト API キー）はすべての BYOK 操作に自動的にアクセスできます。

スコープ文字列は大文字・小文字を区別し、動詞を先頭に置く小文字形式です （read:byok、BYOK:Read ではありません）。

キーをセットする

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });

const key = await client.byok.set("project_xyz", "openai", process.env.MY_OPENAI_KEY!);

console.log(key.api_key_prefix); // 例 "sk-..." ── キー本体は決して返らない
console.log(key.health_status);  // 同期プローブ通過後は "healthy"

一覧と確認

const keys = await client.byok.list("project_xyz");
for (const k of keys) {
console.log(k.provider, k.api_key_prefix, k.health_status, k.last_used_at);
}

有効化／無効化／削除

PATCH はキーを差し替えずに is_active を切り替えます ── 一時的に 止めたいがキー本体は残しておきたい時に。DELETE はキーと履歴を 完全に消します。

// この BYOK キーを一時停止（以後の呼び出しはプラットフォーム課金に戻る）
await client.byok.setActive("project_xyz", "openai", false);

// 再テスト
const fresh = await client.byok.test("project_xyz", "openai");

// 完全に削除
await client.byok.delete("project_xyz", "openai");

キャッシュと無効化

プラットフォームは性能のため、解決済みの BYOK キーを (project_id, provider) 単位でプロセス内にキャッシュします。 Set / Patch / Delete のたびに無効化が走るので、ローテートしたキーは 再起動なしで次回呼び出しから反映されます。

BYOK が適用されないケース

そのチャット呼び出しが落ち着いたプロバイダに対し、プロジェクトに BYOK キーが存在しない場合、Sonzai はプラットフォーム自身のキーで 普通に課金します ── UX も SLA も同じです。BYOK は 加算的 な 機能で、キーをセットするとそのプロバイダだけを引き取り、消すと プラットフォーム キーに戻ります。

リファレンス

• Custom LLM (BYOM) ── プロバイダ パススルーではなく、エンドポイント自体を自分で持つ。
• Reference → API → BYOK ── すべてのエンドポイントの REST スキーマ。