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

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つのマシンキーを複数人で共有したりしないでください。理由はオフボーディングです。人が退職したりサービスを廃止したりした際、付随的な影響なしに、正確に必要な認証情報だけを無効化できる必要があります。

サービスアカウントも同じ目的を果たします。人に紐づかないIDをマシンワークロードに与え、独自のスコープを設定できるため、監査証跡の正確性を保てます。

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

監査と検知

これまでの段階では、漏洩時の被害を減らす方法を説明しました。この段階では、そもそも漏洩が発生したかどうかを検知する方法を説明します。適切な検知は、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、データ保持

認証は、より広範なコンプライアンス評価の一要素です。ここで主張できることとできないことを慎重に扱う必要があります。以下はユースケースに対する判断ではなく、事実に基づく出発点として捉えてください。

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

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

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

キーをサーバー側だけに置くことで、最大の漏洩経路をなくせます。単回使用トークンは、実際にAPIへのアクセスが必要なクライアントにもその保証を広げます。スコープ設定と環境ごとの分離により、1件の漏洩による被害を抑えられます。設定にローテーションを組み込むことで、復旧をリスクではなく定常作業にできます。ワークスペース制御は、人間用とマシン用のIDを区別します。監査により、不正利用を請求額の予期せぬ変化ではなくアラートとして把握できます。文書化されたランブックは、インシデントを手順化します。

これは、高価値なあらゆるシークレットを保護するのと同じ認証情報の衛生管理です。ここで扱うキーには、費用を発生させ、大規模にオーディオを生成できるという固有の価値があります。

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

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

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

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

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

関連記事

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

営業に相談サインアップ