独自キーの持ち込み(BYOK)
組織は、上流プロバイダの独自キーを持ち込めます。モデルが組織の資格情報を通る経路になると、ゲートウェイはプラットフォームの資格情報ではなく、その組織のキーでプロバイダに認証します。クライアントは同じゲートウェイキー(yb_…)を使い続けます。クライアント側の変更は不要です。
キーを追加できる人
管理コンソールの組織管理者です。場所は Settings → Provider keys です。すべてのキーは追加した組織に属し、その組織のトラフィックにだけ使われます。
対応プロバイダ
| プロバイダ | レジストリ種別 | base_url | 注記 |
|---|---|---|---|
| OpenAI | openai | https://api.openai.com/v1 | |
| Anthropic | anthropic | https://api.anthropic.com | Messages API |
| Z.AI (Coding Plan) | zai-coding | https://api.z.ai/api/coding/paas/v4 | エンドポイントはアダプタが固定します。YABANIN_ZAI_CODING_ENABLED を有効にしてください(プロバイダ を参照) |
| vLLM | openai-compat | http://<host>:8000/v1 | OpenAI 互換サーバ |
| Ollama | openai-compat | http://<host>:11434/v1 | Ollama の OpenAI 互換エンドポイント |
| カスタム | openai-compat | 任意の HTTPS の OpenAI 互換 base_url | llama.cpp、LM Studio、ゲートウェイ、… |
キーの追加
- 組織管理者として管理コンソールにサインインします。
- Settings → Provider keys に移動し、Add key をクリックします。
- Name(例:
prod-openai)、Provider、Base URL、プロバイダの API key を入力します。 - 保存します。コンソールは直ちに last-4 マスクだけを表示します。平文は二度と表示されません。
- 任意: Test connection は、コンソールから登録済みの base URL へ、保護されたプローブを送ります(組織ごとにレート制限されます。サーバはテスト履歴を保持しません)。
- そのプロバイダのモデルへリクエストを経路付けします。ゲートウェイは組織キーで上流に認証します。
Ollama の例
base_url は http://127.0.0.1:11434/v1、プロバイダは openai-compat です。ゲートウェイがコンテナ内で動く場合(クイックスタートの compose)、代わりにホストのループバックである http://host.docker.internal:11434/v1 を指します。
資格情報の解決
リクエストが上流の資格情報を必要とするとき、ゲートウェイは次の順で解決します。
| 順序 | 階層 | 使われる条件 |
|---|---|---|
| 1 | 組織キー(BYOK) | リクエスト元の組織が Settings → Provider keys に、プロバイダと上流 base URL(完全一致、または /v1 を除いた形)に一致する有効なキーを持っている。最新の一致が優先されます。 |
| 2 | モデルごと | 組織キーが一致しなかった場合。モデルレジストリ項目に固定された資格情報です。 |
| 3 | グローバル | 上記のどちらでもない場合。ゲートウェイに設定されたプラットフォーム全体の資格情報です。 |
3つの階層すべてで、経路、予算、リネージ、監査は同じです。異なるのは上流の認証だけです。
保存されるものと見えるもの
- 保存されるもの: 暗号化された暗号文(
api_key_ct)と last-4 マスクだけです。それ以外はありません。保管時の平文コピーは存在しません。 - コンソールと管理 API で見えるもの: 名前、プロバイダ、base_url、last-4 マスクです。キーそのものは見えません。
- 平文はリクエスト時にメモリ上でのみ使われます。ログには残らず、作成後に API が返すこともありません。
- 組織の分離(RLS): キー行は行レベルセキュリティのもとで、その組織にスコープされます。別の組織は見ることや解決することはできません。
トラブルシューティング
httpの base_url が拒否される。 リモートのプロバイダはhttps://を使う必要があります。平文のhttp://が受け入れられるのは、ローカルの Ollama と vLLM が動くように、ループバックホスト(127.0.0.1、localhost)だけです。平文httpのリテラルなプライベート IP エンドポイント(vLLM、TGI)を登録するオンプレミス導入では、管理サーバにYABANIN_ORG_CRED_ALLOW_HTTP_PRIVATE=1を設定できます。ホスト名の対象はどのモードでもhttpsのみのままです。予約済み範囲(ループバック、リンクローカル / メタデータ)はダイヤル時に禁止されたままです。リモートのものには前段に TLS を置いてください。DNS と TLS のランブック を参照してください。- キーが解決されない。 解決順をたどります。(1) 組織は Settings → Provider keys に、有効で一致するキーを持っているか。プロバイダが一致し、base URL がモデルの上流 URL(または
/v1を除いた形)と等しいか。(2) モデルレジストリ項目のモデルごとの資格情報が、それを覆い隠していないか。(3) グローバル資格情報は存在するか。誤っている最初の階層を直します。 - 別の組織からキーが見えない。 設計どおりです。RLS はすべてのキー行をその組織にスコープします。キーを所有する組 織にサインインしていることを確認してください。
スタンドでの確認
make quickstart-up && make quickstart-seed— スタンドを立ち上げます。表示された管理者パスワードと API キーを保管します。http://127.0.0.1:8086を開き、admin@localhostとしてサインインします。- Settings → Provider keys → Add key: 名前
local-ollama、プロバイダopenai-compat、base_urlhttp://host.docker.internal:11434/v1、キーollama。保存された行には名前、base_url、last-4 マスクが表示されます。キーそのものは表示されません。 - シードされたキーで、ゲートウェイ経由のチャットを行います。
curl -sS -H "Authorization: Bearer yb_…" -H "Content-Type: application/json" -d '{"model":"<ollama-backed registry model>","messages":[{"role":"user","content":"ping"}]}' http://127.0.0.1:8082/v1/chat/completions→200となり、Ollama がリクエストをログに残します(組織キーが上流で認証した証明です)。 - 否定確認: base_url
http://10.0.0.1:8000/v1のキー追加を試します → デフォルトでは拒否されます(ループバックを超えた平文 http。導入がYABANIN_ORG_CRED_ALLOW_HTTP_PRIVATE=1を設定している場合を除きます)。 - 否定確認: 2つ目の組織としてサインインします → Provider keys は空です(RLS)。
- 組織キーを削除して手順 4 を繰り返します。リクエストは依然として解決されます(モデルごと / グローバル階層経由)。手順 4 が組織キーを使っていたことの確認です。
制限
- BYOK が変えるのは上流の認証だけです。ゲートウェイのクライアントキー(
yb_…)、予算、方針、監査は変わりません。 - キー素材はエクスポート、再ダウンロード、組織間の移動ができません。
- Last-4 は表示用マスクにすぎず、キーが有効である証明にはなりません。