OpenAI API 身份验证上手指南：从 API Key 到 OAuth 2.0 的正确选择-育师

OpenAI API 身份验证上手指南：从 API Key 到 OAuth 2.0 的正确选择

【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi

第一次执行curl请求，返回了 401 Unauthorized。我当时也不确定：是密钥填错了，还是压根就不该用密钥？这篇关于 OpenAI API 身份验证的文章写给还没对接过 OpenAI 的开发者。读完你会知道该选 API Key 还是 OAuth 2.0，能跑通第一次成功调用，并会查 401、403 这类报错。

选型先行：哪种验证方式适合你

别急着看文档，先回答三个问题：

你的应用跑在哪一侧？只在你自己的服务器上运行，用你自己的账户调接口，API Key 就够用。
要不要代某个用户访问 OpenAI 数据？如果密钥属于终端用户，你只是"代跑"，那就需要 OAuth 2.0。
密钥由谁保管？需要把凭证分发给别人、或写进客户端代码，密钥随时会外泄，应走 OAuth 2.0 授权流程。

复杂度上的差别一句话带过：API Key 就是一个请求头；OAuth 2.0 涉及用户授权、令牌交换和到期刷新，链路更长。服务器端自用选 API Key，第三方应用选 OAuth 2.0，下面分别演示。

用 API Key 跑通第一次调用

🗝️ 密钥获取与安全注入

到 OpenAI 控制台的 API Keys 页面创建密钥。密钥以sk-开头，后接一串随机字符，本文一律用sk-xxxx表示，你看到的任何sk-后接长字符串的文本都应当心。

注入方式只用环境变量：

export OPENAI_API_KEY=sk-xxxx

预期结果：终端执行echo $OPENAI_API_KEY能打印出完整密钥。注意 openapi.yaml 里把默认认证方式ApiKeyAuth定义为http+bearer，也就是说密钥永远通过Authorization: Bearer请求头传递，SDK 和库都是这么做的，你不需要手写这个头。

第一次成功调用

用最简单的GET /v1/models做首次调用，它不消耗模型额度，只读列出可用模型。

cURL：

curl https://api.openai.com/v1/models \ -H "Authorization: Bearer $OPENAI_API_KEY"

Python（openai库默认读取OPENAI_API_KEY环境变量）：

from openai import OpenAI client = OpenAI() # 密钥自动取自环境变量 models = client.models.list() for m in models.data[:5]: print(m.id)

预期结果：两者都返回 HTTP 200。cURL 输出一个 JSON，"object": "list"，data数组里是模型条目（含id、object、owned_by等字段）；Python 终端依次打印出前 5 个模型 ID。看到模型 ID 说明认证链路已通，之后换成POST /v1/chat/completions等端点，同一个密钥即可。

三个不要

不要把密钥写进前端代码、浏览器 Bundle 或任何用户能打开的产物里。
不要把密钥提交进仓库——写进.env并把.env加进.gitignore，提交前git grep sk-查一遍。
不要让开发和生产共用同一把密钥，分开创建，出事时影响面可控。

什么时候该上 OAuth 2.0

场景是：你做了一个第三方应用，用户用自己的 OpenAI 账户登录你的应用，你的代码需要读取该用户的对话、用量等数据。这时绝不能让用户把 API Key 交给你，正确的做法是 OAuth 2.0 授权码流程：

用户在 OpenAI 授权页登录并同意授权，动作方是用户；
OpenAI 回调你的应用，带回一个一次性的授权码，动作方是OpenAI 授权服务器；
你的后端拿授权码向授权服务器换取访问令牌，动作方是你的应用；
之后每次调 API，在请求头带上Authorization: Bearer <access_token>，动作方是你的应用；
访问令牌到期前，用刷新令牌换一张新的访问令牌，动作方是你的应用。

预期结果：用户在授权页点"允许"后，你的回调地址会收到code参数；用该参数换到的access_token可直接发起 API 请求并得到 200。

报错排查速查

遇到 OpenAI 401 错误，先按下表定位，不用翻代码：

错误信号	可能原因	验证动作
401 Unauthorized	请求头没带密钥、格式不对，或密钥已失效	抓一次实际请求，确认`Authorization`头是`Bearer`+ 完整密钥、无多余空格；到控制台 API Keys 页查该密钥是否被吊销
403 Forbidden	密钥没有访问该端点的权限，或账户有欠费	对照所调端点，在控制台确认该密钥的权限范围；检查 Billing 页有无未支付账单
令牌过期（OAuth 2.0 请求返回 401/403）	访问令牌超出有效期	记录令牌的签发时间与有效期，到期前改用刷新令牌换新令牌后重放请求