BYOK（キーの保存）

Bring your own keys（BYOK）は Cloudflare AI Gateway の機能です。AI プロバイダーの API キーを Cloudflare ダッシュボードに安全に保存できます。毎回のリクエストに API キーを含めず、ダッシュボードで一度設定し、ゲートウェイ設定から参照します。

キーは Secrets Store に安全に保存され、次のことができます。

• 安全に保管し、露出を抑える
• キーのローテーションを簡単にする
• Dynamic Routes でレート制限、予算制限、その他の制限を適用する

• ゲートウェイが 認証済み であること。
• Secrets Store でシークレットを作成・デプロイする 権限 があること。

BYOK はダッシュボードまたは API で設定できます。

ダッシュボードからプロバイダーキーを追加すると、AI Gateway が Secrets Store のシークレットを自動で作成し、名前を付けます。

1. Cloudflare ダッシュボード ↗ にログインし、アカウントを選択します。
2. AI > AI Gateway に移動します。
3. ゲートウェイを選択するか、新規作成します。
4. Provider Keys セクションを開きます。
5. Add API Key を選択します。
6. ドロップダウンから AI プロバイダーを選択します。
7. API キーを入力し、必要に応じて説明を追加します。
8. Save を選択します。

API で BYOK を設定する場合は、プロバイダー設定の前に Secrets Store のシークレットを作成します。シークレット名は次の形式にします。

{gateway_id}_{provider_slug}_{alias}

たとえば、ゲートウェイ my-gateway、プロバイダー anthropic、エイリアス default の場合、Secrets Store のシークレットは次の名前にします。

my-gateway_anthropic_default

その後、同じ provider_slug と alias でプロバイダー設定を作成します。

Secrets Store が返す secret_id は、AI Gateway の実行時ルックアップには使いません。API で作成するシークレットは、この命名規則に従う必要があります。

ダッシュボードで API キーを設定したら、次を行います。

1. コードから API キーを削除する: ハードコードした API キーや環境変数を削除します。
2. リクエストヘッダーを更新する: プロバイダーの認可ヘッダーをリクエストから外します。cf-aig-authorization は引き続き渡す必要があります。
3. 連携をテストする: API キーなしでリクエストが通ることを確認します。

BYOK を有効にすると、流れは次のように変わります。

1. 従来の方法: 毎回のリクエストヘッダーに API キーを含める

   curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
     -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
     -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model": "gpt-4", "messages": [...]}'

2. BYOK の方法: ダッシュボードでキーを一度設定し、キーを露出させずにリクエストする

   curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
     -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
     -H "Content-Type: application/json" \
     -d '{"model": "gpt-4", "messages": [...]}'

AI Gateway ダッシュボードでは次ができます。

• プロバイダーごとに設定済み API キーを一覧する
• 各キーの最終使用日時を確認する
• 各キーの状態（active、expired、invalid）を確認する

API キーをローテーションするには:

1. AI プロバイダーで新しい API キーを発行します
2. Cloudflare ダッシュボードで既存のキーエントリを編集します
3. 古いキーを新しいキーに置き換えます
4. 変更を保存します

アプリケーションは、コード変更やダウンタイムなしで、すぐに新しいキーを使い始めます。

API キーを削除するには:

1. AI Gateway ダッシュボードで削除するキーを探します
2. Delete ボタンを選択します
3. 削除を確認します

AI Gateway では、同じプロバイダーに複数の API キーを保存できます。これにより次ができます。

• 用途ごとに異なるキーを使う（例: 開発と本番）
• ローテーション中にキーを段階的に移行する

各 API キーには、識別用のエイリアスを付けられます。キー追加時にカスタムエイリアスを指定できます。指定しない場合、システムは default を使います。

リクエスト時、AI Gateway はデフォルトで default エイリアスのキーを使います。別のキーを使うには、cf-aig-byok-alias ヘッダーに使いたいキーのエイリアスを指定します。

複数の OpenAI キーを異なるエイリアス（例: default、production、testing）で設定している場合、使うキーを指定できます。

# Uses the key with alias "default" (no header needed)
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [...]}'

# Uses the key with alias "production"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
  -H 'cf-aig-byok-alias: production' \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [...]}'

# Uses the key with alias "testing"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
  -H 'cf-aig-byok-alias: testing' \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [...]}'