API Key 是什么，如何获取和正确配置
副标题：以 OpenAI 为例，讲清从创建、保存、环境变量、调用，到权限与安全防护的完整流程。
| 适合谁看 | 刚接触 API 的新手、站长、开发者、AI 工具使用者、需要把模型接入网站或脚本的人 |
| 你会学到 | API Key 的本质、获取入口、环境变量配置、服务端接入方式、团队权限设置、泄漏排查与轮换 |
| 阅读提示 | 本文以 OpenAI 为例，但“不要写死到前端、统一走服务端、用环境变量或 Secrets 管理”的原则适用于大多数 API 平台 |
| 先记住一句话： API Key 不是“给前端拿去直连模型”的钥匙，而是给你的服务端或受控环境用来代表你发请求的机密凭证。只要一个 key 暴露出去，别人就可能以你的身份调用接口、消耗额度，甚至带来额外费用。 |
很多人第一次接触 API 时，最容易混淆的就是账号、登录态、API Key、Access Token 这些概念。尤其在 AI 工具越来越多之后，用户常常会在“能不能直接把 key 填进网页里”“拿到 key 后到底写到哪里”“为什么代码明明能跑却还是报错”这些问题上反复踩坑。真正高频出问题的地方，往往不是接口本身，而是凭证管理方式。
这篇文章会把 API Key 讲成一条完整链路：先理解它是什么，再知道去哪里创建，然后学会正确保存、正确配置、正确调用，最后补上生产环境里最重要的安全习惯。你不需要一开始就把所有平台都弄懂，只要先把这套基本方法吃透，以后接触其他厂商的 API，也会很快上手。
图 1｜API Key 从创建到安全调用的典型链路
一、API Key 到底是什么
API Key 可以理解成“程序访问某个平台接口时使用的机密身份凭证”。在 OpenAI 的官方说明里，API 请求使用 API keys 做身份验证；请求发到服务器后，平台会根据你带过去的 key 来识别你是谁、你属于哪个组织或项目、你有没有权限调用某个端点，以及这次调用应该记到哪一份用量里。
它和你在网页上登录 ChatGPT 的账号密码不是一回事。账号密码是给人登录控制台或网页端用的，而 API Key 是给程序、脚本、后端服务发请求时用的。也正因为如此，它的安全要求会更高：你不能把它随便复制给别人，也不能把它明文写在浏览器脚本、移动端 App、公开仓库或截图里。
| 把几个常见概念区分开： 账号密码：用于登录平台控制台或网页。API Key：用于你的程序调用接口，常见形式是 sk-… 或项目级密钥。环境变量：操作系统里的变量名和值，用来安全地把 key 注入程序，而不是把 key 写死在代码里。Bearer Authentication：HTTP 里携带 key 的常见方式，格式通常是 Authorization: Bearer <API_KEY>。 |
二、为什么不能把 API Key 直接写到前端或代码仓库里
OpenAI 官方安全指南里有三条非常核心的提醒：不要把 key 部署在浏览器或移动端等客户端环境；不要把 key 提交到代码仓库；推荐用环境变量或密钥管理服务来替代硬编码。原因很现实——客户端代码最终会被用户拿到，仓库也可能被爬虫、第三方依赖、协作者或意外公开事件看到。一旦 key 泄漏，就等于别人可以冒用你的身份发起请求。
很多新手觉得“我的网站还没流量”“只是临时测试一下”就问题不大，实际上恰恰是临时测试最容易把 key 粘到错误的地方。比如直接把 key 放在 JavaScript 里、把示例文件原样推到 GitHub、把屏幕录制或截图发到群里，这些都是非常常见的泄漏方式。
- 不要把 key 写进浏览器端 JS、Vite/Next.js 前端公开环境、微信小程序前端直连代码、移动端 App 安装包。
- 不要在博客、论坛、教程截图、README、Notion 公开页面里展示完整 key。
- 不要在团队里共用同一个 key；官方建议每个成员单独使用自己的 key。
- 如果已经怀疑泄漏，不要观望，先 rotate（轮换）再排查。
图 2｜把 API Key 的安全管理当成生产能力的一部分
三、以 OpenAI 为例：API Key 到哪里获取
OpenAI Help Center 的说明非常直接：你的 Secret API key 可以在 API key page 找到。当前平台里，常见做法是先登录 OpenAI API Platform，然后进入组织或项目设置，在对应的 API Keys 页面创建新的 secret key。
- 登录 OpenAI API Platform 控制台。
- 进入 Organization settings 或选定具体 Project。
- 打开 API Keys 页面，点击“Create new secret key”或类似按钮。
- 立即复制新生成的 key，并保存到安全的位置。
这里有一个很重要的细节：某些 key（尤其是服务账号创建时生成的 secret key）通常只会在创建当下完整显示一次。官方在项目管理文档中明确提醒，创建后应立即保存；如果丢失，通常需要重新生成新的 key，而不是事后在页面里把原值完整找回来。
| 获取 key 时最容易忽视的两点： 先想清楚你要把这个 key 用在哪个项目，而不是随手在默认组织下乱建。复制后立刻保存到密码管理器、Secrets 管理器或本地受控文档，不要只放在剪贴板里。 |
四、正确配置 API Key：优先环境变量，其次 Secrets 管理服务
OpenAI 官方最佳实践推荐把变量名统一设置为 OPENAI_API_KEY，并通过操作系统环境变量把 key 提供给你的程序。这样做的好处是：代码仓库里不需要出现真实 key；团队里的变量名一致；后续轮换时，只需更新环境而不需要在很多脚本里全文搜索替换。
对本地开发来说，环境变量已经足够实用；对线上服务来说，更推荐把 key 存在云平台的 Secrets / Key Management Service 里，由容器、函数或服务器实例在运行时注入。原则只有一个：程序可以读到，仓库和前端看不到。
图 3｜OpenAI 官方给出的环境变量配置思路，适合本地开发快速上手
1）Windows CMD 示例
在新的 cmd 窗口里验证变量是否生效
| setx OPENAI_API_KEY “<yourkey>” echo %OPENAI_API_KEY% |
注意：官方说明里提到，setx 对未来新开的 cmd 窗口生效，所以你执行完之后，需要重新打开一个新的命令行窗口再验证。很多人明明执行过 setx，却马上在当前窗口里跑脚本，结果依然报未找到变量，就是因为这个细节。
2）macOS / Linux（zsh）示例
zsh 环境常见写法
| echo “export OPENAI_API_KEY=’yourkey'” >> ~/.zshrc source ~/.zshrc echo $OPENAI_API_KEY |
如果你使用 bash，官方建议把 .zshrc 换成 .bash_profile。总之，本质都是把 export 语句写到启动脚本里，再让终端重新加载。
3）本地开发时的常见组织方式
- 代码里只写 os.getenv(“OPENAI_API_KEY”) 或等价读取方式，不写明文。
- 若项目使用 .env 文件，也要把 .env 加到 .gitignore，避免提交到仓库。
- 前端项目把所有对 OpenAI 的调用转到自己的后端接口，由后端读取环境变量并转发请求。
- 线上环境优先使用云厂商提供的 Secret Manager、KMS、Environment Variables 等受控注入机制。
五、正确调用方式：只让服务端带着 key 去请求 API
在认证方式上，OpenAI 官方 API 文档给出的方式非常明确：使用 HTTP Bearer authentication，也就是在请求头里携带 Authorization: Bearer OPENAI_API_KEY。对于需要显式指定组织或项目的场景，还可以附加 OpenAI-Organization 和 OpenAI-Project 头。
最小 Bearer 认证示例
| curl https://api.openai.com/v1/models -H “Authorization: Bearer $OPENAI_API_KEY” |
当你需要显式指定组织 / 项目时
| curl https://api.openai.com/v1/models -H “Authorization: Bearer $OPENAI_API_KEY” -H “OpenAI-Organization: $ORGANIZATION_ID” -H “OpenAI-Project: $PROJECT_ID” |
如果你是做网站、工具页或自动化脚本，推荐的调用链路应该是：前端发请求给你自己的后端；后端读取环境变量里的 OPENAI_API_KEY；后端再向 OpenAI API 发起请求，并把结果返回前端。这样就算前端代码被任何人查看，也拿不到你的真实 key。
官方 Quickstart 风格的首个请求示例
| curl https://api.openai.com/v1/responses -H “Content-Type: application/json” -H “Authorization: Bearer $OPENAI_API_KEY” -d ‘{ “model”: “gpt-5.4”, “input”: “用一句话解释什么是 API Key” }’ |
| 前端 / 后端职责建议： 前端：只负责收集用户输入、展示结果，不接触真实 key。后端：读取环境变量、加鉴权头、校验请求、记录日志、处理报错。运维 / 平台层：管理 Secrets、轮换 key、监控用量与异常流量。 |
六、团队和生产环境怎么做才算“正确配置”
对单人测试来说，能跑起来就算第一步；但到了团队协作和线上环境，就不能只停留在“有一个 key 能调通”的阶段。OpenAI 的项目管理文档给了几条很实用的做法：项目级 key 可以在具体项目的 API Keys 页面创建和管理；key 权限可以设置为 All、Restricted、Read Only；服务账号可以创建专门的系统访问账号，并且这些账号和 key 都是项目作用域的。
- 成员各自使用自己的 key，不要整个团队共用一个 secret。
- 按项目划分 key，把测试、正式、不同业务拆开，便于记账与权限控制。
- 能用 Restricted 就别默认 All；只读场景用 Read Only。
- 自动化任务、定时作业、CI/CD、服务端 worker 更适合使用服务账号。
- 设置项目预算提醒与使用量监控，尽早发现异常增长。
权限模型怎么理解
在项目设置里，OpenAI 当前提供三种 key 权限层级：All、Restricted、Read Only。All 是全部权限；Restricted 允许你按端点做 None / Read / Write 的细分；Read Only 则适合只读类场景。对新手来说，你可以把它理解为“不要默认给满权限”。能最小授权，就最小授权。
服务账号什么时候用
如果请求不是由具体某个成员在自己电脑上跑，而是由服务器、定时任务、后台 worker、部署流水线来跑，就更适合创建 service account。这样做的好处是：你可以把“系统身份”跟“个人身份”分开；某个成员离职或角色变动时，不会影响系统服务本身的运行。官方也提醒，服务账号创建后生成的 secret key 需要立即保存，因为之后不能再次完整查看。
七、常见报错与排查方法
配置 API Key 时，最常见的问题并不是代码逻辑，而是凭证本身或凭证注入方式。OpenAI Help Center 专门列出了“Incorrect API key provided”这一类报错的排查思路，核心包括：检查你当前使用的 key 是否正确、确认应用里没有混用不同 key、必要时确认组织设置是否正确。
高频问题 1：Incorrect API key provided
- 先去 API Keys 页面核对你现在程序里用的那一串是否还是当前有效 key。
- 确认程序没有从旧的 .env、旧容器镜像、旧 CI 变量里读取到过期值。
- 检查是否前后端或多个脚本混用了两把不同的 key。
- 如果你属于多个组织或历史遗留项目，检查是否需要显式指定组织 / 项目头。
高频问题 2：环境变量明明设置了，但程序读不到
- Windows 使用 setx 后要重新打开新的命令行窗口。
- macOS / Linux 写入 .zshrc 或 .bash_profile 后，要重新 source 或重开终端。
- IDE、Docker、PM2、systemd、Serverless 平台各自有自己的环境变量注入位置，别只在本地 shell 里设置。
- 打印一次变量名是否拼写正确，例如 OPENAI_API_KEY，而不是 OPEN_API_KEY 之类的近似名。
高频问题 3：已经怀疑 key 泄漏
- 立即 rotate 或删除旧 key，并生成新 key。
- 同步更新本地开发环境、服务器、CI/CD、Secrets 管理平台里的值。
- 查看 Usage / 成本记录，确认是否出现异常调用。
- 检查 Git 历史、日志、错误上报平台、公开页面和截图，确认泄漏入口。
八、一页配置清单：把“能用”升级为“用得对”
| 发布前自查 10 项： 我知道这把 key 属于哪个项目、谁在用、用来干什么。真实 key 没有出现在前端代码、公开仓库、截图或文档里。程序通过环境变量或 Secrets 管理服务读取 key，而不是写死在代码中。前端不会直接请求 OpenAI API，一律走自己的后端。本地、测试、生产环境的 key 已分开。团队成员没有共用同一把 key。关键服务使用项目级 key 或服务账号，而不是个人临时 key。至少配置了使用量查看与预算提醒。我知道如何快速 rotate key，并完成替换。我已经为常见报错准备了最小排查清单。 |
结语
API Key 看起来只是平台后台里的一串字符，但它背后代表的其实是一套完整的工程习惯：最小暴露、最小权限、后端托管、环境变量注入、分项目管理、及时轮换与审计。真正成熟的做法，不是“抄一段示例代码能跑起来”，而是让这把 key 在不同环境里都始终处于可控状态。
如果你刚开始接触 API，建议先用本文的方法把本地环境配置通，再把前端直连改成后端转发。等你的网站、脚本或自动化任务真正跑起来之后，再补上项目级权限、服务账号、预算提醒和轮换策略。只要这套底层方法建立起来，以后无论你接入哪个 AI API，都会轻松很多。
附录：官方资料来源（用于本文校对）
| 来源 | 本文使用位置 |
| OpenAI Help Center｜Where do I find my OpenAI API Key? | 说明 secret API key 的获取入口在 API key page。 |
| OpenAI Help Center｜Best Practices for API Key Safety | 说明不要把 key 放到客户端、不要提交到仓库、推荐使用 OPENAI_API_KEY 环境变量，并给出 Windows / macOS / Linux 示例。 |
| OpenAI API Reference｜Authentication | 说明使用 Bearer 认证，以及在需要时附加 OpenAI-Organization / OpenAI-Project 头。 |
| OpenAI Help Center｜Managing projects in the API platform | 说明项目级 API keys、权限级别 All / Restricted / Read Only、服务账号与预算提醒。 |
| OpenAI API Quickstart / Production best practices | 说明第一条请求示例与生产环境中的密钥存放建议。 |
FAQ ：
API Key 是什么？
它是程序访问 API 时使用的机密凭证，用来完成身份验证与权限判断。
OpenAI API Key 到哪里获取？
登录 OpenAI API Platform 后，在组织或项目的 API Keys 页面创建新的 secret key。
为什么不能把 API Key 写到前端？
因为浏览器、移动端或公开仓库里的代码最终会被他人看到，暴露后可能带来额度消耗与安全风险。
最推荐的配置方式是什么？
本地用环境变量，线上用 Secrets 或 Key Management Service，由服务端读取后再调 API。
遇到 Incorrect API key provided 怎么办？
先核对当前 key 是否有效，再检查是否混用旧 key、环境变量未生效，必要时重新生成新 key。
