API キーの使い方

包括的な開発者ガイドとベストプラクティスで、すばやく開発を始められます。

チュートリアル

ヘッダーへの付与、環境変数からの注入、ローテーション、漏洩時の対応 SOP まで、本番プロジェクトで API キーを安全に使う流れをまとめます。

API キーは Abestar に対する唯一の認証手段です。本章では取得方法（「認証」を参照）の繰り返しは避け、入手後の置き方・差し替え・事故対応に焦点を絞ります。

ヘッダーへの付与

認証が必要な全エンドポイントは X-API-Key ヘッダーを読みます。例は環境変数 ABESTAR_API_KEY にキーが格納されている前提で記述します。

シェルから環境変数経由でキーを使用します。

bash

# Set once per shell session
export ABESTAR_API_KEY="sk_live_..."

# Use it on every authenticated request
curl -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello", "target_language": "zh-TW" }'

Node 側で process.env からキーを取得します。

javascript

// Server-side fetch — read from process.env, never bundle the key
const res = await fetch("https://abemono.abestar.com.tw/api/v1/translations/text", {
    method: "POST",
    headers: {
        "X-API-Key": process.env.ABESTAR_API_KEY,
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        text: "Hello",
        target_language: "zh-TW",
    }),
});

キーをフロントエンドに置かない

キーがブラウザに渡れば誰でも取得できます。必ずサーバ経由でリクエストをプロキシするか、BFF のサーバ側で付与してから転送してください。フロントエンドバンドル、公開接頭辞付きの環境変数（NEXT_PUBLIC_* / VITE_*）、公開リポジトリにはキーを置かないでください。

キーのローテーション

アカウントごとに最低 2 本のキーを保持し、以下の手順で無停止のローテーションを行います。コンソールは同時複数本の有効化に対応しており、旧キーの無効化までは新旧キーが同時に有効です。

コンソールで新キーを作成し、旧キーは一時的に有効のままにします。
新キーをシークレットマネージャや環境変数に書き込み、関連サービスを再デプロイします。
24〜72 時間ほど観察し、全インスタンスが新キーへ切り替わり、401 unauthorized が増えていないことを確認します。
コンソールで旧キーを無効化します。以降、旧キーでのリクエストは 401 unauthorized となります。

漏洩時の対応 SOP

キーが誤ってバージョン管理やフロントエンドバンドルに混入した場合は、以下の手順を直ちに実施します。事後レビュー向けに各ステップの時刻を記録してください。

コンソールで漏洩キーを直ちに無効化します。無効化は不可逆かつ即時反映されます。
新キーを発行し、シークレットマネージャとデプロイ環境を更新します。
影響リポジトリ、git 履歴、CI ログのいずれにも旧キーが残らないように確認します。git 履歴に残る場合は履歴を書き換えるか repo を再作成します。
直近の使用記録に、異常なリクエスト量、想定外のエンドポイント呼び出し、見覚えのない地理的アクセスがないか確認します。
漏洩経路を振り返り、再発防止策（pre-commit のシークレットスキャン、env テンプレート、CI でのシークレット検査）を追加します。