ドキュメントはじめに認証
認証
3 種類の認証ヘッダー、キーの形式とライフサイクル、認証関連のエラー。
すべてのデータプレーンリクエスト（/v1/* と /v1beta/*）には API キーが必要です。3 社の SDK と互換にするため、ゲートウェイは以下の順で 3 種類の認証ヘッダーを確認します。いずれか 1 つで認証できます：
| ヘッダー | 形式 | 代表的なクライアント |
|---|---|---|
Authorization | Authorization: Bearer sk-sole-…（Bearer プレフィックスなしのキー単体も可） | OpenAI SDK · Codex |
x-api-key | x-api-key: sk-sole-… | Anthropic SDK · Claude Code |
x-goog-api-key | x-goog-api-key: sk-sole-… | Google GenAI SDK |
URL クエリパラメータ（Google 公式の ?key= など）でのキー指定はサポートしていません。クエリ文字列はアクセスログやブラウザ履歴に残り、漏えいリスクが高いためです。必ずヘッダーで指定してください。
キーの形式とライフサイクル
キーは sk-sole- で始まります。完全なキーは作成時に一度だけ表示され、サーバーはハッシュのみを保存します。紛失したキーは復元できず、再作成のみ可能です。各キーには個別に以下を設定できます：
- 有効/無効：いつでもワンクリックで無効化でき、利用履歴は保持されます。
- 有効期限：一時的な連携やサードパーティへの受け渡しに便利です。
- 利用上限：USD 建ての上限で、日/週/月ごとの自動リセットも選べます。上限に達するとそのキーのリクエストは拒否されます（HTTP 402）。
- IP 許可リスト：呼び出し元 IP を制限できます。リスト外からのリクエストは拒否されます（HTTP 403）。
認証関連のエラー
| 状況 | HTTP | メッセージ id |
|---|---|---|
| キー未指定 | 401 | key_missing |
| キーが存在しないか削除済み | 401 | key_invalid |
| キーが無効化されている | 403 | key_disabled |
| キーの有効期限切れ | 403 | key_expired |
| 送信元 IP が許可リスト外 | 403 | key_ip_denied |
| キーの利用上限に到達 | 402 | key_quota_exhausted |
| アカウントが停止されている | 403 | account_disabled |
エラーレスポンスの形式はリクエストパスに対応する SDK の形式になり、メッセージはアカウントの言語設定（認証前は Accept-Language、既定は英語）にローカライズされます。詳細はエラーコードを参照。
セキュリティのベストプラクティス
- キーは環境変数またはシークレットマネージャーに保存し、ソースコードや設定リポジトリに書かないでください。
- ブラウザなどクライアント側コードにキーを埋め込まないでください。フロントエンドから直接呼ぶ必要がある場合は、小さな上限と IP 許可リストを付けた専用キーを使います。
- 用途ごとにキーを分けると、利用の分離と事故時の影響範囲の限定（該当キーだけ無効化）ができます。
- キーは定期的にローテーションし、一時的な用途には有効期限と利用上限を設定してください。