ElevenAPI 的 API 认证与密钥管理

API 身份验证是服务确认传入请求是否有权操作某个账户的方式。例如，使用 ElevenAPI 时，API 凭据可授权消耗按量计费额度、大规模生成语音和音乐，以及在某些部署中访问敏感音频的请求。

密钥泄露会造成费用损失，还可能被用于以账户名义生成内容。它也可能为平台提供权限过大的访问，从而带来数据泄露和其他攻击途径的风险。早在 2020 年，超过 90% 的开发者就在至少一项日常流程中使用 API。如今，随着模型上下文协议（MCP）和 AI 应用兴起，API 已无处不在。

本文介绍如何正确验证 API，以及如何在密钥的整个生命周期内进行管理：范围限制、轮换、组织控制、审计和事件响应。它将帮助团队正确设置 API 身份验证和密钥管理。阅读时，可同时打开 身份验证参考文档 和 一次性令牌参考文档。

摘要

• ElevenAPI 通过单一密钥 xi-api-key 请求头验证每个请求，这意味着任何持有密钥的人都能消耗额度，并以该账户名义生成音频。
• 绝不要将长期有效的 API 密钥发布到浏览器、移动应用或用户可检查的其他任何制品中。应将其保存在你控制的服务器上。
• 客户端场景必须使用服务器端签发的短期一次性令牌进行身份验证，绝不能使用长期密钥。
• 可通过按最小权限限制密钥范围、为每个环境分配独立密钥并定期轮换，降低泄露影响范围。
• 审计和异常检测有助于防止密钥泄露和意外情况。

什么是 API 身份验证？

API 身份验证是服务在开始处理前，确认传入请求是否有权操作特定账户的方式。请求方提供凭据，服务对其进行验证，验证通过后再返回响应。

简单来说，它回答的是：此请求是否有权代表该账户操作？需要注意，这与 API 授权不同；API 授权定义已通过身份验证的请求在系统中可以执行哪些操作。

什么是密钥管理？

密钥管理是指用于管理 API 密钥整个生命周期的一系列实践。它决定如何创建、存储、使用、轮换密钥，以及如何撤销密钥访问权限。这些机制用于端到端保障 API 密钥安全。

完善的密钥管理体系可防止密钥泄露，并降低其被公开访问的风险。

为何 API 密钥安全至关重要：威胁模型

既然已定义身份验证和密钥管理，就应准确了解密钥处理不当会造成什么后果。先分析威胁模型，能让后续每项实践都有明确目的：要么降低密钥泄露概率，要么减轻泄露后的损失。

ElevenAPI 通过单一的密钥机制进行身份验证：xi-api-key 请求头。任何持有密钥的人都可获得授权，请求本身没有第二重验证因素。

持有密钥的人可以消耗额度。文本转语音、语音转文本、音乐和音效都按量计费，攻击者只要持有有效密钥，就能持续生成，直至额度或余额耗尽。

他们可以大规模生成内容，而我们的限流模型使这一情况比表面看上去更严重。限制基于并发数，而非简单的每分钟请求配额。若某个套餐对特定模型系列的并发限制为 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",
});

在生产环境中，应在进程启动时从密钥管理器（AWS Secrets Manager、GCP Secret Manager、HashiCorp Vault 或平台的同类服务）加载密钥，而不是将其固化到镜像中，或提交包含它的 .env 文件到仓库。

用于客户端应用的一次性令牌

首要原则不可妥协，但许多合理的场景需要客户端本身访问 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 拒绝。这是目前处于预览阶段的企业版功能，可通过账户经理获取。

最后，不要在开发、预发布和生产环境之间共用密钥。应为每个环境签发独立密钥，分别设置范围和配额。按环境划分的密钥可避免开发者笔记本电脑上的泄露影响生产额度，可在不干扰其他环境的情况下轮换单个环境，还能让使用日志更易解读，因为流量已按来源分段。

API 密钥轮换

密钥轮换是定期用新密钥替换旧密钥的做法。每当怀疑发生泄露或暴露时，也应执行这一操作。

按计划轮换还能缩短未被发现的泄露可被利用的时间窗口。只有代码从一开始就为轮换而设计，轮换才不会带来麻烦，因此应在需要之前做好设计。

核心方法是密钥重叠，可实现零停机切换：

1. 生成新的 API 密钥： 在现有密钥之外配置一个新密钥，并保持相同的范围、配额和 IP 限制。此时两个密钥都有效。
2. 更新密钥： 在密钥管理器中更新密钥并让实例加载它（根据设置，可能是重启、重新读取或刷新密钥管理器）。
3. 确认流量： 验证流量正在使用新密钥。观察用量，确认旧密钥已不再有流量。
4. 移除密钥访问权限： 当旧密钥在一段安全时间内未显示任何流量后，撤销它。

由于两个密钥在重叠期间都有效，因此不会出现请求因缺少凭据而失败的时刻。重叠窗口还有第二个好处：配置错误的实例会继续使用旧密钥，从而暴露自身，你可以在禁用该密钥前找到它。

要让重叠切换平稳无感，应将代码设计为轮换只是配置变更，而非代码变更。从可刷新的单一位置读取密钥，并让单个开关决定哪个密钥处于活动状态。

// 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 天例行轮换一次是合理默认值；高价值或访问广泛的密钥应更频繁轮换，发生任何暴露时则应立即轮换。可通过定时任务自动配置、切换、验证和撤销密钥，将轮换从一次事件变为后台流程。

工作区访问控制和权限

范围限制和轮换保障单个密钥安全，而工作区控制则管理谁能签发密钥。它提供了制定和遵循组织策略的空间，并会影响未来所有密钥管理实践。

首先区分人员凭据和机器凭据。人员使用自己的账户和权限登录控制台；服务则使用密钥，或更佳的服务账户进行身份验证。不要让服务运行在通过个人访问权限签发的密钥上，也不要让人员共用一个机器密钥。原因在于离职或下线：当某人离开或服务退役时，需要精确撤销对应凭据，避免附带影响。

服务账户也服务于这一目标。它为机器工作负载提供不绑定个人的身份，并具备独立的范围限制，使审计记录真实可靠。

然后按角色分配访问权限，而非逐一分配给个人。工作区正是为此支持群组和成员权限。授予每个群组完成工作所需的最小权限，定期审查成员资格，并确保没有任何单一凭据（无论人员还是机器）拥有超出其角色所需的权限。

审计和检测

前面介绍了如何减轻泄露的损失。本节将说明如何检测是否发生了泄露。良好的检测依赖于 3 个习惯。

第一，记录哪个密钥（按标识符记录，绝不记录密钥值）服务了哪类请求、请求来自何处及请求量。应从所有日志和追踪层中清除 xi-api-key 请求头。在 HTTP 中间件和 APM 配置中设置脱敏规则，可杜绝密钥进入日志存储最常见的途径。

第二，监控额度消耗异常。跟踪每个密钥的额度消耗趋势，并针对偏离基线的情况发出告警：例如突然激增、在异常时段生成，或本应闲置的密钥突然活跃。

第三，关注并发请求头。我们会在每个响应的 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 的客户端。范围限制和按环境隔离可限制单次泄露的损失。将轮换纳入配置，可使恢复成为常规操作而非风险操作。工作区控制让人员和机器身份保持独立。审计让滥用变成告警，而不是账单上的意外。书面的操作手册则将事件转化为可执行的流程。

这与保护任何高价值密钥所需的凭据卫生实践相同，只是该密钥的特殊价值在于它能消耗资金并大规模生成音频。

准备好根据真实请求格式接入时，可在身份验证参考文档和一次性令牌参考文档中查看当前支持的端点列表。若要了解监控应跟踪的并发模型，接下来可阅读模型参考文档和 API 快速入门。

保护 ElevenAPI 集成安全

强大的 API 身份验证是一项基础控制措施，许多其他安全实践都建立在其之上。采取仅在服务器端使用密钥、为客户端部署一次性令牌、按最小权限限制范围，以及将轮换纳入密钥管理等措施，有助于大规模降低风险。

如需了解支持的端点和应使用的准确请求头格式，请参阅 ElevenAPI 文档。如果已准备好开始，请申请 ElevenLabs API 密钥，立即开始构建。

API 身份验证和密钥管理常见问题