セキュリティ

APIキー管理

• キーをハードコードしないでください — 環境変数またはシークレットマネージャー（AWS Secrets Manager、GCP Secret Manager、HashiCorp Vault）を使用してください
• キーをGitにコミットしないでください — .env を .gitignore に追加してください。git-secrets または truffleHog でリポジトリ履歴をスキャンしてください
• 環境ごとに個別のキーを使用してください — 開発/ステージング/本番キーは独立しています。開発キーが漏洩しても本番には影響しません
• すべてのキーにスコープを設定してください — モデルアクセスを制限し、利用上限を設定し、作成時にすべてのキーをIPホワイトリストに登録してください

キーローテーション

APIキーは 90日 ごとにローテーションしてください。以下は検証付きの安全なローテーション手順です：

import os
import requests

# Step 1: Create new key via Dashboard or API
NEW_KEY = "sk-new-key-from-dashboard"

# Step 2: Update environment (do this atomically with your deploy)
# In production, use a secrets manager: AWS Secrets Manager, GCP Secret Manager, or Vault
os.environ["TOKSPAN_API_KEY"] = NEW_KEY

# Step 3: Verify new key works
response = requests.post(
    "https://api.tokspan.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {NEW_KEY}"},
    json={"model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}]},
    timeout=10,
)
assert response.status_code == 200, f"New key validation failed: {response.status_code}"

# Step 4: Revoke old key in Dashboard → API Keys
# Only do this AFTER confirming new key works in production
print("New key validated. Revoke old key in Dashboard now.")

バックエンドプロキシ（ブラウザ/モバイルで必須）

クライアントサイドコードから直接TokSpanを呼び出さないでください。 ブラウザやモバイルアプリで公開されたAPIキーは誰でも抽出できます。常にバックエンド経由でルーティングしてください：

Browser App → Your Backend API → TokSpan API
                      ↑
              API key lives here
          (never reaches the client)

バックエンドがユーザーのセッションを検証し、サーバーサイドのAPIキーでAIリクエストを転送します。クライアントがキーを目にすることはありません。

IPホワイトリスト

各APIキーを特定のIPアドレスまたはCIDR範囲に制限します。キーが漏洩しても、許可されていないネットワークからは使用できません。ダッシュボード → APIキー → 編集 → IPホワイトリスト で設定してください。本番キーについては、バックエンドサーバーの送信IPのみをホワイトリストに登録してください。

MFAの有効化

TokSpanダッシュボードアカウントを 多要素認証（MFA） で保護します。TOTP認証アプリ（Google Authenticator、Authy、1Password）で利用可能です。ダッシュボード → 設定 → セキュリティ → MFA で有効にしてください。

監査と監視

異常検知のためにキー使用量をログに記録します：

# Monitor API key usage via response headers
import logging

def audit_request(response, key_name):
    usage = response.json().get("usage", {})
    logging.info(f"[{key_name}] model={response.json()['model']} "
                 f"tokens={usage.get('total_tokens', 0)} "
                 f"remaining_rpm={response.headers.get('x-ratelimit-remaining-requests', '?')}")

ダッシュボードで、キーごとに アクティビティログ を定期的に確認してください。確認すべき項目：予期しないモデル使用、トークンの急増、不明なIPからのリクエスト、通常と異なる時間帯の使用。

キーが漏洩した場合

1. 直ちに失効させてください — ダッシュボード → APIキー → 失効（60秒以内に反映）
2. 新しいキーを生成してください — アプリケーションを更新してください
3. 古いキーのログを監査してください — 削除前に不正使用がないか確認してください
4. 漏洩経路を調査してください — Git履歴、CIログ、エラーメッセージ、クライアントサイドコードを確認してください
5. スコープを強化してください — 交換用キーにIPホワイトリストを追加し、利用上限を引き下げてください