コンテンツへ移動
ログイン登録
お問い合わせログイン

ElevenAPIのAPI認証とキー管理

執筆者
Tadas Petra
Jack Limebear
公開日
最終更新日

聴くこの記事を聴く

始める
詳しく見る

API認証とは、受信したリクエストにアカウント上で操作する権限があることをサービスが確認する仕組みです。たとえば、ElevenAPIでは、API認証情報によって、従量制クレジットの消費、大規模な音声・音楽生成、一部のデプロイにおける機密性の高いオーディオの操作を伴うリクエストが認可されます。

キーが漏洩すると、費用が発生するだけでなく、アカウント上でコンテンツを生成されるおそれがあります。また、プラットフォームへの過剰な権限アクセスを許し、データ漏洩やその他の攻撃経路につながる可能性もあります。2020年の時点で、すでに90％以上のデベロッパーが日常業務の少なくとも1つでAPIを利用していました。現在はモデルコンテキストプロトコル（MCP）やAI利用の拡大により、APIはあらゆる場所で使われています。

この記事では、APIを正しく認証する方法と、スコープ設定、ローテーション、組織的な管理、監査、インシデント対応まで、キーのライフサイクル全体を管理する方法を解説します。チームでAPI認証とキー管理を適切に導入するのに役立ちます。読み進める際は、認証リファレンスと単回使用トークンのリファレンスを開いておくと便利です。

概要

  • ElevenAPIは、xi-api-keyヘッダーという単一のシークレットで各リクエストを認証します。つまり、キーを持つ人は誰でも、アカウントのクレジットを消費し、オーディオを生成できます。
  • 長期間有効なAPIキーを、ブラウザ、モバイルアプリ、またはユーザーが検査できるその他の成果物に含めてはいけません。管理下にあるサーバーに保管してください。
  • クライアントサイドのユースケースでは、サーバー側で発行した短期間有効な単回使用トークンで認証し、長期間有効なキーは絶対に使用しないでください。
  • 最小権限でキーのスコープを設定し、環境ごとにキーを分離して、定期的にローテーションすることで、漏洩時の影響範囲を抑えられます。
  • 監査と異常検知は、キー漏洩や予期せぬ事態の防止に役立ちます。

API認証とは？

API認証とは、サービスが処理を開始する前に、受信したリクエストに特定のアカウント上で操作する権限があることを確認する仕組みです。リクエスト元が認証情報を提示し、サービスが検証したうえで、レスポンスを返します。

簡単に言うと、「このリクエストには、このアカウントに対して操作する権限があるか？」という問いに答える仕組みです。このプロセスは、認証済みリクエストがシステム内で実行できる操作を定めるAPI認可とは異なります。

キー管理とは？

キー管理とは、APIキーのライフサイクル全体を管理するための幅広い実践方法を指します。キーの作成、保管、使用、ローテーション、アクセス取り消しの方法を定めます。これらの仕組みにより、APIキーのセキュリティをエンドツーエンドで確保します。

厳格なキー管理体制を整えることで、キー漏洩を防ぎ、公開状態になるリスクを減らせます。

APIキーのセキュリティが重要な理由：脅威モデル

認証とキー管理を定義したところで、キーを不適切に扱った場合に何が起きるのかを正確に把握しましょう。まず脅威モデルを確認することで、以降に紹介する各対策の目的が明確になります。いずれも、キーが漏洩する可能性、または漏洩時の被害を減らすためのものです。

ElevenAPIは、xi-api-keyヘッダーという単一のシークレットベースの仕組みで認証します。キーを持つ人は誰でも認証され、リクエスト自体に第2の認証要素はありません。

キーを持つ人は、クレジットを消費できます。テキスト読み上げ、スピーチtoテキスト、音楽、サウンドエフェクトはいずれも従量課金対象であり、有効なキーを持つ攻撃者は、クォータまたは残高が尽きるまで生成を継続できます。

また、大規模な生成も可能です。レート制限モデルにより、この問題は見た目以上に重大になります。制限は単純な毎分リクエスト数ではなく、同時実行数に基づきます。特定のモデルファミリーで同時実行数が5に制限されたプランのキーでも、意味のある数の生成を同時に維持できます。こうした制限を理解している攻撃者は、悪用を並列化します。

アカウント上でコンテンツを生成される可能性もあります。キーで生成されたオーディオはすべてワークスペースに紐づくため、使用する音声や入力内容によっては、評判上、場合によっては法的な懸念につながります。

キーが漏洩する経路はありふれたもので、ほかのあらゆる認証情報が漏洩する場合と同じ失敗パターンです。

  • クライアントサイドコード内のAPIキー：ブラウザバンドル、モバイルバイナリ、シングルページアプリに含まれたキーは、実質的に公開情報です。ミニファイは難読化ではありません。
  • リポジトリ内のAPIキー：Gitにコミットされたハードコードキー。後に公開されたり広く複製されたりするプライベートリポジトリ、追跡対象にする意図のなかった.envなどのファイルも含まれます。
  • ログとトレース内のAPIキー：リクエストロガー、エラートラッカー、オブザーバビリティパイプラインは、日常的にHTTPヘッダーを取得します。xi-api-key内のキーは、ログストア、APMベンダー、そしてそれらへの読み取りアクセスを持つすべての人に渡ってしまいます。
  • CIとスクリーンショット内のAPIキー：ビルドログ、サポートチケット、共有ターミナル。

以下の各セクションでは、こうしたリスクの発生確率または影響を減らす方法を説明します。

絶対原則：APIキーはサーバー側に保管する

この記事のほかの内容も、APIキーの認証・管理リスクを減らすための知見を提供します。しかし、この原則がすべての土台であり、何よりも優先して実装すべきものです。

仕組みが非常にシンプルだからこそ、長期間有効なAPIキーは管理下にあるサーバーだけに置くことが絶対原則です。ブラウザ、モバイルアプリ、デスクトップクライアント、またはユーザーがダウンロードして検査できる成果物に含めてはいけません。キーがクライアントサイドコードにある場合は、すでに侵害されたものとして扱ってください。

SDKはELEVENLABS_API_KEYを自動的に読み取るため、最もシンプルなコードでは何も渡さず、クライアントを一度だけ初期化します。

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

// Reads process.env.ELEVENLABS_API_KEY when apiKey is omitted - never a literal.
const elevenlabs = new ElevenLabsClient();

const audio = await elevenlabs.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Generated entirely server-side.",
  modelId: "eleven_flash_v2_5",
  outputFormat: "mp3_44100_128",
});

本番環境では、イメージに埋め込んだりリポジトリにコミットした.envに保存したりするのではなく、プロセス起動時にシークレットマネージャー（AWS Secrets Manager、GCP Secret Manager、HashiCorp Vault、またはプラットフォームの同等機能）から読み込んでください。

クライアントサイドアプリ向けの単回使用トークン

この絶対原則に例外はありませんが、クライアント自体がElevenAPIにアクセスする必要がある正当なユースケースも多くあります。たとえば、ストリーミングのテキスト読み上げを再生するブラウザ、文字起こし用のオーディオを録音するモバイルアプリ、ユーザーのタブで実行されるリアルタイムエージェントなどです。長期間有効なキーをそこに置くことはできません。解決策は、漏洩しても低リスクな認証情報、つまり短期間有効な単回使用トークンをクライアントに渡すことです。

サーバーは長期間有効なキーを保持し、独自のセッションロジックでユーザーを認証・認可してから、短期間有効なトークンを発行し、それだけをクライアントに渡します。トークンはすぐに期限切れになり、発行された操作にスコープが限定されるため、漏洩しても価値は低く、すぐに無価値になります。対応エンドポイントと正確なリクエスト形式については、単回使用トークンのリファレンスを確認してください。

これはブローカーエンドポイントの基本ロジックです。独自のセッションロジックでユーザーを認可し、ドキュメント化されたトークンエンドポイントに対してトークンを発行します。リクエストはサーバーから長期間有効なxi-api-keyを使って送信され、クライアントに返されるのは生成された短期間有効なトークンだけです。

// ... express app and route boilerplate
app.post("/api/voice-token", async (req, res) => {
  // 1. Authorize the user with YOUR session/auth system first.
  if (!req.session?.user) return res.status(401).json({ error: "unauthorized" });

  // 2. Mint a short-lived token server-side. The long-lived key travels only
  //    in this server-to-server request, never to the browser.
  const response = await fetch("https://api.elevenlabs.io/v1/tokens", {
    method: "POST",
    headers: {
      "xi-api-key": process.env.ELEVENLABS_API_KEY as string,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}), // populate per the tokens reference
  });

  // 3. Return only the short-lived token. The API key never leaves the server.
  res.json({ token: await response.json() });
});

その後、ブラウザはトークンを使って接続するため、長期間有効なキーがページに入ることはありません。

最小権限へのキーのスコープ設定

最小権限とは、各キーにはその役割に必要な権限だけを与え、それ以上は与えないという原則です。ElevenAPIでは、キーに許可・禁止する操作を制限する、複数の権限ベースの制約を設定できます。

すべての権限を持つ単一のキーは、影響範囲という点で最悪のケースであり、安易に選ばれがちなデフォルトでもあります。より良い方法は、どのキーもいずれ漏洩することを前提に、漏洩してもその役割に必要な範囲でしか操作できないようにすることです。

まずは、キーが呼び出せるAPIエンドポイントを制限するスコープ制限から始めましょう。文字起こし専用のキーにテキスト読み上げへのアクセスは不要です。また、音楽機能用のキーが音声管理にアクセスする必要もありません。

次に、クレジットクォータを設定します。キーごとにカスタムのクレジット上限を割り当てることで、漏洩時の金銭的被害を抑え、自身のコードで発生する暴走ループも制限できます。

IPホワイトリストはさらに強力です。キーを特定のIPアドレスまたはCIDR範囲に制限でき、ホワイトリストにないIPからのリクエストは403で拒否されます。これは現在プレビュー中のエンタープライズ機能で、アカウントマネージャーを通じて利用できます。

最後に、開発、ステージング、本番環境でキーを共有しないでください。環境ごとに、それぞれ独自のスコープとクォータを持つ別個のキーを発行します。環境別のキーにより、デベロッパーのノートPCからの漏洩が本番環境のクレジットに及ぶのを防げます。また、ほかの環境に影響を与えずに1つの環境だけをローテーションでき、トラフィックが発信元ごとにすでに分割されているため、利用ログも解釈しやすくなります。

APIキーのローテーション

キーのローテーションとは、定期的にキーを新しいものへ置き換える運用です。侵害や露出が疑われる場合にも実施します。

定期的なローテーションは、気付かれていない漏洩が悪用される期間も短縮します。ローテーションを無理なく行うには、コードがそのために設計されている必要があります。必要になる前から、ローテーションを前提に設計してください。

中核となる手法はキーのオーバーラップで、ダウンタイムなしで切り替えられます。

  1. 新しいAPIキーを生成する：既存キーと並行して、同じスコープ、クォータ、IP制限を持つ新しいキーをプロビジョニングします。これで両方のキーが有効になります。
  2. キーを更新する：シークレットマネージャー内のシークレットを更新し、インスタンスに新しいキーを読み込ませてロールアウトします。設定に応じて、再起動、再読み込み、またはシークレットマネージャーの更新を行います。
  3. トラフィックを確認する：新しいキーでトラフィックが流れていることを確認します。利用状況を監視し、古いキーへのトラフィックが停止したことを確認してください。
  4. キーアクセスを削除する：安全な期間にわたってトラフィックがないことを確認したら、古いキーを無効化します。

オーバーラップ中は両方のキーが有効なため、認証情報がないことでリクエストが失敗する瞬間はありません。オーバーラップ期間にはもう1つ利点があります。設定を誤ったインスタンスは古いキーを使い続けるため、そのキーを停止する前に特定できます。

オーバーラップを問題なく行うには、ローテーションがコード変更ではなく設定変更になるようコードを構成してください。更新可能な箇所でキーを一元的に読み込み、1つのスイッチでどのシークレットを有効にするか決めます。

// Rotation is driven by configuration, not code edits. The secret manager (or
// the deploy that injects env vars) is the single point of change.
// ELEVENLABS_KEY_ACTIVE selects which slot is live, enabling overlap.
let client: ElevenLabsClient | undefined;

function activeKey(): string {
  const slot = process.env.ELEVENLABS_KEY_ACTIVE ?? "primary";
  const name = slot === "primary" ? "ELEVENLABS_API_KEY_PRIMARY" : "ELEVENLABS_API_KEY_SECONDARY";
  return process.env[name] as string;
}

function getClient(): ElevenLabsClient {
  return (client ??= new ElevenLabsClient({ apiKey: activeKey() }));
}

// Call after a secret refresh to pick up the rotated key without a deploy.
function resetClient(): void {
  client = undefined;
}

オーバーラップ中はPRIMARYとSECONDARYの両方を設定し、ELEVENLABS_KEY_ACTIVEを切り替えます。アプリケーションコードを変更する必要はありません。

頻度については、バックエンドキーでは90日ごとの定期ローテーションが妥当なデフォルトです。価値が高いキーや広くアクセスされるキーでは、より高頻度に実施し、露出が発生した場合は直ちに行ってください。プロビジョニング、ロールアウト、検証、無効化をスケジュールジョブで自動化すれば、ローテーションをイベントではなくバックグラウンドプロセスにできます。

ワークスペースのアクセス制御と権限

スコープ設定とローテーションが個々のキーを保護する一方で、ワークスペースの制御は、そもそも誰がキーを発行できるかを管理します。組織のポリシーを定義・運用する場となり、今後のすべてのキー管理の実践に影響します。

まず、人間とマシンの認証情報を分離してください。ユーザーは個別のアカウントと権限でダッシュボードにサインインし、サービスはキー、またはより望ましいサービスアカウントで認証します。個人のアクセス権から発行されたキーでサービスを実行したり、複数の人が1つのマシンキーを共有したりしてはいけません。理由はオフボーディングです。担当者が退職したりサービスが廃止されたりしたとき、ほかに影響を及ぼすことなく、適切な認証情報だけを無効化できる必要があります。

サービスアカウントも同じ目的に役立ちます。マシンワークロードに、人間に紐づかないアイデンティティと独自のスコープを与えるため、監査証跡の正確性を保てます。

次に、アクセス権を個人ごとではなくロールに割り当てます。ワークスペースは、この目的のためにグループ権限とメンバー権限をサポートしています。各グループが業務を行うのに必要な最小権限を付与し、メンバーシップを定期的に見直してください。人間でもマシンでも、単一の認証情報がそのロールに必要な範囲を超えて操作できない構成を目指しましょう。

監査と検知

これまでの段階では、漏洩による被害を減らす方法を説明してきました。ここでは、そもそも漏洩が発生したかどうかを検知する方法を解説します。効果的な検知は、3つの習慣に基づきます。

1つ目は、どのキーが（シークレット値ではなく識別子で）どの種類のリクエストを、どこから、どの程度の量で処理したかを記録することです。すべてのログ記録・トレース層からxi-api-keyヘッダーを除去してください。HTTPミドルウェアとAPM設定にマスキングルールを設けることで、キーがログストアに流出する最も一般的な経路を遮断できます。

2つ目は、クレジット消費の異常を監視することです。キーごとのクレジット消費量を継続的に追跡し、ベースラインからの逸脱をアラートにします。たとえば、急激な増加、通常とは異なる時間帯での生成、アイドル状態であるはずのキーの突然の活動などです。

3つ目は、同時実行数ヘッダーの監視です。各レスポンスでは、current-concurrent-requestsヘッダーとmaximum-concurrent-requestsヘッダーで、現在および最大の同時リクエスト数を返します。これにより利用可能な余力を把握でき、自分で開始していない最大値への張り付きが続く場合は、強い不正利用シグナルです。生のHTTPエンドポイントを使用すると、レスポンスヘッダーに直接アクセスできます。

const resp = await fetch("https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb", {
  method: "POST",
  headers: {
    "xi-api-key": process.env.ELEVENLABS_API_KEY as string,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Monitoring headroom.", model_id: "eleven_flash_v2_5" }),
});

const current = resp.headers.get("current-concurrent-requests");
const maximum = resp.headers.get("maximum-concurrent-requests");
// Emit these to your metrics pipeline; alert on sustained saturation you did not cause.

これらのシグナルでアラートが発報されるようにしてください。誰も見ていないダッシュボードでは検知になりません。クレジット急増と同時実行数飽和のシグナルを、障害時に使うアラート経路へ組み込み、明確な担当者を定めましょう。

インシデント対応

どれほど優れたセキュリティ・監視システムを導入していても、キーはいずれ漏洩するものと考える必要があります。被害を抑えるための手順をあらかじめ用意しておけば、対応のロードマップとなり、時間と影響を抑えられます。

APIキーが露出した場合に備えた、事前定義のインシデント対応フローは次のとおりです。

  1. 漏洩したキーを直ちに無効化する：影響範囲を完全に把握するまで待たないでください。無効化されたキーでは生成できず、必要であればいつでも代替キーを発行できます。これが最も価値の高い対応です。
  2. 新しいキーにローテーションする：漏洩したキーが本番トラフィックを処理していた場合は、オーバーラップ手順を逆に適用します。新しいキーを用意してトラフィックを切り替え、漏洩したキーが無効になったことを確認します。コードは設定からキーを読み込むため、必要なのは設定の切り替えであり、コード変更ではありません。
  3. 利用ログから影響範囲を評価する：漏洩を封じ込めた後、その影響を定量化します。キーはどれほどの期間、有効かつ露出した状態でしたか？その間に消費されたクレジットはどれくらいで、パターンは正当なトラフィックと一致していますか、それとも不正利用ですか？どのエンドポイントにアクセスされましたか？
  4. 依存するシークレットをローテーションする：キーだけが単独で漏洩することはほとんどありません。リポジトリ、ログストア、CIパイプラインで露出した場合は、同じ場所にあるほかのシークレットも露出したと仮定し、それらもローテーションしてください。
  5. 漏洩経路を塞ぐ：キーがどのように流出したかを特定して修正してください。修正しなければ再発します。ファイルを.gitignoreに追加して履歴から削除する、ロガーにヘッダーマスキングを追加する、シークレットをビルド成果物から取り除く、CIシステムへのアクセスを厳格化する、といった対策を行います。
  6. ポストモーテムを作成する：タイムライン、影響範囲、根本原因、追加した具体的な対策（スコープの厳格化、IPホワイトリスト、CIでのシークレットスキャナー、より短いローテーション周期）を記録します。

これらの手順に従えば、API露出という重大なシナリオに対応するための、頼れるプロセスを整備できます。

コンプライアンスの状況：SOC 2、HIPAA、データ保持

認証は、より広範なコンプライアンス評価における1つの要素です。ここで何を主張でき、何を主張できないかには注意が必要です。以下はユースケースに対する判断ではなく、事実に基づく出発点として扱ってください。

ElevenLabsはSOC 2に準拠しています。対象となるプランとユースケースでは、HIPAA準拠とゼロリテンションモードを利用できます。ゼロリテンションとは、リクエストのコンテンツが処理後に保存されないことを意味します。入力や生成されたオーディオに機密性がある場合に重要です。

特定のモードが適用されるかどうかは、プラン、設定、処理する内容の詳細によって異なります。利用する前に、アカウントの適格性と正確な条件を確認し、上記のアクセス制御と組み合わせてください。コンプライアンス認証はプラットフォームによるデータの取り扱いを規定し、キー管理は誰があなたに代わって操作できるかを規定します。後者はあなた自身が管理する領域です。

適切なAPIキーセキュリティとは

キーをサーバー側だけに置けば、最大の漏洩経路を排除できます。単回使用トークンにより、APIへアクセスする必要があるクライアントにもこの保証を広げられます。スコープ設定と環境ごとの分離で、個々の漏洩による被害を限定できます。設定に組み込まれたローテーションにより、復旧はリスクのある作業ではなく日常的な運用になります。ワークスペース制御により、人間とマシンのアイデンティティを分離できます。監査により、不正利用を請求書上の驚きではなくアラートとして検知できます。文書化されたランブックにより、インシデントを手順化できます。

これは、あらゆる高価値シークレットを保護するための認証情報衛生と同じ考え方を、大規模なオーディオ生成とクレジット消費が可能なキーに適用したものです。

実際のリクエスト形式で実装する準備ができたら、認証リファレンスと単回使用トークンのリファレンスで、現在サポートされているエンドポイント一覧を確認してください。監視で追跡すべき同時実行モデルについては、モデルリファレンスとAPIクイックスタートが次に読むべき資料です。

ElevenAPIインテグレーションを保護する

強力なAPI認証は、多くのセキュリティ対策の基盤となる重要な制御です。キーをサーバー側だけで使用する、クライアントに単回使用トークンを導入する、最小権限でスコープを設定する、キー管理にローテーションを組み込むといった対策は、大規模なリスク防止に役立ちます。

対応エンドポイントと使用する正確なヘッダー形式について詳しくは、ElevenAPIドキュメントを参照してください。準備ができたら、ElevenLabsのAPIキーをリクエストして、今日から開発を始めましょう。

API認証とキー管理に関するよくある質問

関連記事

最高品質のAIオーディオで創造する

営業に相談サインアップ