API Key 是什么？一文看懂用途、调用方式与安全管理
简答：API Key 可以理解为“程序调用服务时使用的通行凭证”。它通常是一串随机字符，用于让 API 服务识别请求来源、关联项目或用量，并按服务规则执行访问控制；但它不一定等同于用户登录身份，也不是所有 API 都把它当作完整授权凭证。实际使用前，应以具体服务的认证文档为准，确认密钥放在请求头、Bearer 认证还是查询参数中。
定义：API Key（API 密钥）是由 API 提供方签发、供程序请求接口时携带的凭证，常用于识别调用项目、统计用量、关联配额和实施访问限制。
先看结论：API Key 解决什么问题
如果你刚开始接入 AI、地图、天气或支付接口，可以先记住一句话：API Key 是程序调用服务时使用的通行凭证，但不必然代表某个具体用户的完整身份。
| 作用 | 说明 | 需要注意 |
|---|---|---|
| 识别调用方 | 让服务知道请求来自哪个项目、应用或密钥。 | 有些 API Key 只能识别项目，不能识别具体用户。 |
| 关联配额与计费 | 服务商可以按密钥或项目统计请求量、额度和使用情况。 | 具体计费、限速和配额由服务商定义。 |
| 访问控制 | 服务端可以拒绝缺少密钥、密钥无效或超出权限的请求。 | API Key 的权限强弱不统一，不能默认拥有全部能力。 |
| 故障排查 | 按密钥区分不同应用，有助于定位异常请求或用量来源。 | 需要结合状态码、响应正文和服务端日志判断。 |
AWS 将 API Key 描述为用于控制 API 访问、识别 API 使用并监控用量的字母数字字符串，同时特别说明 API Key 不一定用于验证特定用户身份。Google Cloud 也区分了用于关联项目、配额和计费的标准 API Key，以及绑定服务账号的授权密钥。AWS：什么是 API 密钥、Google Cloud：管理 API Key。aws.amazon.com
API Key 是怎么工作的？先确认认证位置
一次典型的 API 调用大致经过以下流程：客户端准备接口地址、请求方法、请求参数和认证信息；服务端读取密钥并检查格式、有效期、限制条件、权限或配额；检查通过后返回数据，检查失败则返回错误响应。
- 确认服务文档规定的最终请求 URL和 HTTP 方法。
- 确认认证字段名称，例如
X-API-Key、Authorization或服务专用字段。 - 确认 API Key 的放置位置：请求头、Bearer 值，或查询参数。
- 使用最小请求验证连通性，不要一开始就测试流式输出、工具调用等高级能力。
- 检查 HTTP 状态码、响应体中的可识别文本，以及服务返回的 request-id 或错误编号。
API Key 并不存在一个对所有服务都适用的固定写法。Swagger 文档展示了两种常见形式：放在请求头，例如 X-API-Key: <YOUR_API_KEY>；或作为查询参数，例如 ?api_key=<YOUR_API_KEY>。但实际字段名必须以目标 API 的官方文档为准。Swagger：API Key 认证方式。swagger.io
下面只是格式示意，不代表某个具体服务可以直接运行：
- 自定义请求头：
curl https://api.example.com/v1/resource -H "X-API-Key: <YOUR_API_KEY>" - Bearer 认证：
curl https://api.example.com/v1/resource -H "Authorization: Bearer <YOUR_TOKEN_OR_KEY>" - 查询参数：
curl "https://api.example.com/v1/resource?key=<YOUR_API_KEY>"
替换说明：把域名、路径、字段名和占位符都替换为目标服务文档中的值；成功信号是 HTTP 状态正常且响应体包含预期数据；如果返回 401、403 或 404，应依次检查最终 URL、请求方法、模型或资源名称、认证字段和权限，而不是只重复更换 Key。
API Key 与密码、Token、OAuth 有什么区别？
| 凭证 | 主要用途 | 常见特征 |
|---|---|---|
| API Key | 识别项目、应用或调用来源，关联配额、用量和访问限制。 | 常见于服务对服务调用；是否具备细粒度权限取决于服务设计。 |
| 登录密码 | 证明用户可以登录某个账户。 | 通常不应直接放进 API 请求，也不应与 API Key 混用。 |
| Access Token | 代表某个用户、服务账号或授权范围的短期访问凭证。 | 通常有过期时间，可能带有 scope 或角色信息。 |
| Refresh Token | 在授权流程中换取新的 Access Token。 | 生命周期和保存方式通常比 Access Token 更敏感。 |
| OAuth Client ID | 标识 OAuth 应用本身。 | Client ID 通常不是秘密，不能单独证明用户已授权。 |
| OAuth Client Secret | 在部分 OAuth 流程中证明应用身份。 | 应按机密凭证保存，不能随意放入前端代码。 |
因此，“API Key 是不是身份验证”不能只回答是或不是。它可能参与请求认证，也可能只用于识别项目、配额和计费；Google Cloud 明确指出，标准 API Key 不认证调用主体，不能替代 IAM 对调用者权限的判断。OAuth 2.0 则围绕用户或服务主体授权、访问令牌和权限范围展开。Google Cloud：API Key 与授权密钥、Swagger：认证类型。docs.cloud.google.com
什么时候可以放在前端？什么时候必须放在后端？
判断标准不是“它叫不叫 API Key”，而是泄露后能做什么。如果密钥可以触发付费调用、访问私有数据、修改资源、消耗账户额度或绕过重要权限，就应按机密凭证处理，通常由后端保存，前端只调用你自己的后端接口。
- 浏览器、移动端和公开仓库：默认不要内置可产生费用或访问私有资源的密钥。
- 后端服务：使用环境变量、密钥管理服务或平台 Secret 管理功能，不要把真实值写进源代码。
- 开发环境：为本地、测试和生产环境分别使用不同密钥，避免测试代码消耗生产额度。
- 必须公开的场景：有些浏览器端地图或公共数据 API 允许公开使用，但仍应配置来源、域名、IP、接口范围或配额限制。
Google Cloud 建议为 API Key 添加限制、删除不再使用的密钥，并避免把密钥放在 URL 查询参数中，因为 URL 可能进入日志、浏览器历史或扫描记录。OpenAI 的安全指引也建议不要把 API Key 部署到浏览器或移动应用，而应通过自己的后端转发请求。Google Cloud：API Key 安全最佳实践、OpenAI：API Key 安全最佳实践。docs.cloud.google.com
API Key 泄露后怎么办？按这个顺序处理
如果密钥出现在公开仓库、截图、前端打包文件、日志或聊天记录中，不要只删除那一行文本，因为复制者可能已经保存了旧值。建议按以下顺序处理：
- 立即撤销或删除旧 Key：先让泄露的凭证失效。
- 创建新 Key：将新密钥写入环境变量或密钥管理系统。
- 更新应用并做最小验证：确认最终 URL、认证头、状态码和响应体均正常。
- 检查调用记录与账单：查看是否有异常时间段、异常请求量或不熟悉的接口调用。
- 清理泄露源：从仓库、构建产物、日志和文档中移除旧值；如果进入 Git 历史，还要按平台要求清理历史记录。
- 增加限制：按项目、环境、来源 IP、域名、API 范围或权限拆分密钥，并设置合理配额。
OpenAI 的帮助文档建议在怀疑密钥泄露时删除受影响的 Key、检查 API 使用情况并联系支持；其安全建议还包括密钥轮换、环境变量、用量监控和支出阈值。具体撤销入口和审计能力以对应服务控制台为准。OpenAI：账户与 API Key 安全。help.openai.com
面向 AI API 的最小核验清单
接入 AI API 时，可以把 API Key 放到以下核验流程中：
- 协议：先确认服务使用原生协议，还是兼容某种通用接口；不要因为字段名称相似，就默认完全兼容。
- Base URL：确认客户端会不会自动拼接版本路径，例如
/v1；避免重复拼接或漏掉路径。 - 模型字段：使用控制台或接口文档中明确列出的模型标识，不要凭名称猜测。
- 认证：确认是
Authorization: Bearer、X-API-Key还是其他字段。 - 最小请求：先完成一次普通文本请求，再单独验证流式、视觉、工具调用或结构化输出。
- 成功判定：最终请求 URL 和方法正确、HTTP 状态正常、响应体有文本或 JSON 数据，并能关联到 request-id。
如果请求失败，可按“最终 URL → 请求方法 → 模型或资源 → 认证字段 → 响应正文和 request-id → 限速与服务端日志”的顺序排查。404 可能是路由、模型或资源不存在；401 更常见于缺少或无效认证；403 可能涉及权限、来源限制或账户状态；429 通常需要查看服务端给出的限速信息。以上是通用诊断方向，不代表任何单一平台的固定返回规则。
常见问题
API Key 是什么意思？
API Key 是 API Key 的英文名称，中文通常译为 API 密钥或接口密钥。它是一串由服务提供方签发的字符，用于程序调用接口时识别项目或应用，并可能关联配额、用量、权限和计费。
API Key 是不是用户名和密码？
不是。API Key 通常由程序携带，密码主要用于用户登录。API Key 也不一定能代表某个具体用户，是否具备授权能力要看服务的认证设计。
API Key 可以直接写进 JavaScript 前端吗？
默认不建议。浏览器中的代码和网络请求都可能被用户看到。如果密钥能产生费用、访问私有数据或执行高权限操作，应把请求放到后端，由后端保存并使用密钥。
API Key 泄露会有什么后果？
可能导致他人未经允许消耗配额、产生费用、触发接口调用，或在密钥权限较高时访问相关资源。发现泄露后应立即撤销旧 Key、创建新 Key，并检查使用记录。
API Key 放请求头还是 URL 参数？
没有统一答案，必须看目标 API 的官方文档。常见形式包括自定义请求头、Bearer 认证和查询参数；如果服务支持，通常应优先选择更不容易进入 URL 日志的方式。
为什么 API Key 正确仍然返回 401 或 403？
先确认最终 URL、请求方法、认证字段名称、是否重复添加 Bearer 前缀、Key 是否属于正确项目，以及该 Key 是否有对应模型或接口权限。仅仅更换 Key 不一定能解决路由或权限问题。
相关阅读
- AI 工具接入 API Key：先验证 Base URL、模型与密钥
- Codex CLI 配置 API Key：创建、登录与安全排查
- Cursor 配置 API Key：入口、模型与错误排查
- Dify 接入兼容接口：Base URL、模型与认证检查
参考资料
- AWS：什么是 API 密钥？API 密钥和令牌简介（aws.amazon.com）
- AWS：什么是 API？应用程序编程接口简介（aws.amazon.com）
- Google Cloud：管理 API keys（docs.cloud.google.com）
- Google Cloud：API Key 安全最佳实践（docs.cloud.google.com）
- Swagger：API Keys 认证说明（swagger.io）
- Swagger：Authentication 认证类型（swagger.io）
- OpenAI：Best practices for API key safety
- OpenAI：Keeping your account secure
- docs.cloud.google.com（docs.cloud.google.com）