Developer Reference

API Key 从获取到安全使用的完整指南

理解 API Key 的工作原理,学会安全地生成、存储与轮换密钥,避免常见的安全陷阱。

💡

API Key 是什么

API Key 是服务商颁发给调用方的身份凭证,用于标识调用者身份并控制访问权限。它通常由随机字符组成,与服务商平台上的账号或应用绑定。

⚙️

如何获取

登录服务商的开发者控制台,在 API 密钥或 Access Token 页面创建新密钥。创建时通常可以设置密钥的权限范围与过期时间。

🔐

密钥的组成部分

现代 API Key 通常包含前缀(标识服务与类型)、随机生成的秘文主体、以及可选的环境标识,便于快速识别来源与归属。

安全使用四步法

  1. 1

    最小权限

    只为密钥分配完成任务所需的最小权限范围,避免使用具备全部权限的管理员密钥。

  2. 2

    环境隔离

    开发、测试、生产环境使用不同的密钥,发生泄露时可将影响范围控制在单个环境。

  3. 3

    服务端保管

    密钥只应存放于服务端环境变量或密钥管理服务中,绝不写入前端代码或提交到版本库。

  4. 4

    定期轮换

    定期重新生成密钥,并立即吊销不再使用或疑似泄露的密钥,缩短被滥用窗口。

必须避免的常见错误

禁止

把 API Key 硬编码在 index.html 或前端 JS 中

禁止

把含密钥的 .env 文件提交到 git 仓库

禁止

在聊天、截图或公共文档中分享完整密钥

推荐

使用后端代理转发请求,密钥只保存在服务端

推荐

启用访问审计,观察密钥的调用来源与频率

推荐

设置用量告警,异常消费时第一时间吊销密钥

密钥管理演示工具

此工具仅用于演示密钥管理流程。生成的均为格式模拟的虚拟密钥,不含任何真实凭证,并保存在当前浏览器中。

还没有密钥,通过上方表单生成第一个演示密钥。

常见问题

立即在服务商控制台吊销该密钥,随后重新生成一个替换它。同时检查调用记录,评估泄露造成的实际影响,并调整涉及泄露环境的其他配置。

前端代码对任何人可见,密钥一旦随代码分发就等同于公开。即使后端代码,写死在源码里也会随版本历史永久留存,泄露后难以彻底清除。

低频使用的密钥每 90 天轮换一次是常见做法;高权限或高流量密钥应缩短周期。无论周期如何,任何疑似泄露都必须立即轮换。

由后端服务持有密钥并转发请求,前端只与后端通信。后端可在此过程中附加鉴权、限流与审计,密钥始终不进入浏览器环境。