Claude Code / Anthropic API 接入时 Authorization Bearer Token 配置与 401 排错 在配置 Claude Code、自定义 Anthropic API 网关或者调用各类 AI API 时经常会看到这样的请求头Authorization: Bearer YOUR_API_KEY很多开发者第一次配置时会疑惑API Key 本身不就是密钥吗为什么前面还要加一个Bearer一句话解释API Key 是真正的凭证Bearer 是把这个凭证提交给服务端的认证方式。也就是说在Authorization: Bearer xxx里面Authorization是 HTTP 请求头Bearer是认证方案xxx才是真正的 token、API Key 或 access tokenBearer和 token 中间必须有一个空格。如果你正在配置 Claude Code、Anthropic API 兼容网关、OpenAI 风格 API、SaaS API 或企业内部接口这个概念很重要。很多401 Unauthorized、403 Forbidden、鉴权失败、Postman 调不通的问题本质上都是请求头格式写错了。1. Bearer Token 是什么Bearer这个词有“持有者”的意思。Bearer Token 可以理解成一种“谁持有它谁就能访问”的凭证使用方式。它的工作逻辑很直接客户端拿到 token ↓ 请求 API 时放到 Authorization Header ↓ 服务端解析 Bearer 后面的 token ↓ 校验 token 是否有效、是否过期、权限是否足够 ↓ 允许访问或返回 401 / 403需要注意的是Bearer Token 不是某一种固定格式的 token。它可以是一串随机字符串比如sk_xxxOAuth 2.0 里的 access tokenJWT某个平台发给你的 API Key公司内部系统生成的临时访问令牌。所以不要把 Bearer Token 理解成“只有 OAuth 才有”或者“必须是 JWT”。更准确的说法是Bearer 是一种认证提交方式后面的 token 才是真正的凭证。2.Authorization: Bearer token的标准格式Bearer Token 最常见的 HTTP 写法是Authorization: Bearer token示例GET /v1/users HTTP/1.1 Host: api.example.com Authorization: Bearer abc123这里真正的凭证是abc123而不是Bearer abc123Bearer只是告诉服务端“请把后面的字符串当作 Bearer 凭证来处理”。正确格式Authorization: Bearer abc123错误格式 1多了冒号Authorization: Bearer: abc123这个格式是错的Bearer后面不应该有冒号。错误格式 2少了 BearerAuthorization: abc123如果服务端要求 Bearer 认证这种写法可能无法识别。错误格式 3重复写 BearerAuthorization: Bearer Bearer abc123这个问题在 Postman、SDK、封装工具里很常见。比如某个工具已经自动帮你加了Bearer但你在配置里又手动写了一次最终请求就会变成Authorization: Bearer Bearer xxx这类问题经常会导致401 Unauthorized。3. API Key 为什么也要加 Bearer很多人会把 API Key 和 Bearer Token 理解成两种完全并列、互相排斥的东西。其实它们不是同一个层面的概念。API Key 是凭证本身Bearer 是传递凭证的方式。服务商完全可以规定Authorization: Bearer sk-xxxx这句话的意思不是“这个 API Key 变成了 OAuth Token”而是服务端要求你把这个 API Key 按 Bearer 认证格式传过去。这并不代表它一定使用了 OAuth 2.0它一定是 JWT它一定有复杂授权流程它一定比其他 API Key 更安全。本质上这只是客户端和服务端之间的传输约定。服务端代码很可能只是这样处理读取 Authorization 请求头 检查是否以 Bearer 开头 取出后面的字符串 校验这个字符串是否有效同一个 API Key理论上可以有多种提交方式。比如Authorization: Bearer sk-xxxx或者X-API-Key: sk-xxxx也可能是https://api.example.com/v1/users?api_keysk-xxxx到底哪种方式有效完全取决于服务商文档和服务端实现。所以不要看到 API Key 就默认加 Bearer也不要看到 Bearer 就认为它一定是 OAuth Token。最稳妥的做法永远是API 文档要求怎么传就怎么传。4. Claude Code / Anthropic API 接入时要重点检查哪些配置在配置 Claude Code、Anthropic API 或兼容网关时通常需要关注这几类信息API Key Endpoint / Base URL 模型名 Authorization Header 环境变量 请求格式不同工具、SDK、网关的配置项名称可能不同但核心都是这几项。4.1 API Key环境变量里建议只保存 key 本身推荐在环境变量里只保存 token 或 API Key 本身API_KEYabc123不要写成API_KEYBearer abc123除非你的项目代码明确要求环境变量里包含完整前缀。更常见的做法是API_KEYabc123然后在请求时拼接Authorization: Bearer abc123这样更清晰也能避免重复拼接。4.2 Endpoint确认请求打到了正确地址如果你接的是官方 API、企业内部 API或者第三方 Anthropic API 兼容网关都需要确认 Endpoint 是否配置正确。常见问题包括Base URL 写错多写或少写路径使用了错误的协议比如应该是https网关地址和模型接口路径不匹配本地代理、公司网关、容器环境没有正确读取配置。Endpoint 写错时有时不是返回认证错误而是返回404 Not Found或者Connection refused也可能因为请求到了错误服务导致返回类似401的鉴权失败。4.3 模型名不要把鉴权问题和模型名问题混在一起很多 AI API 的请求除了鉴权外还需要传模型名。例如请求体里可能会出现类似字段{ model: model-name, messages: [] }如果 token 正确但模型名不存在、不可用或权限不足也可能出现请求失败。这类问题通常和 Bearer 本身无关需要根据接口返回内容判断。排查时建议分开看401优先检查 API Key、Bearer 格式、环境变量是否正确 403优先检查权限、scope、资源访问授权 404优先检查 Endpoint、路径、模型名 400优先检查请求体格式、字段名、参数结构具体含义仍以服务商接口返回和文档为准。5. 实际请求示例下面用几个常见方式演示 Bearer Token 应该怎么传。5.1 curl 示例curl https://api.example.com/v1/users \ -H Authorization: Bearer YOUR_API_KEY注意Bearer 和 YOUR_API_KEY 中间必须有一个空格不能写成-H Authorization: Bearer: YOUR_API_KEY也不要写成-H Authorization: BearerBearer YOUR_API_KEY5.2 JavaScript fetch 示例fetch(https://api.example.com/v1/users, { headers: { Authorization: Bearer ${apiKey} } })这里apiKey变量通常只保存 key 本身const apiKey abc123不建议保存成const apiKey Bearer abc123否则后面拼接时容易变成Authorization: Bearer Bearer abc123如果你是在浏览器前端代码里调用 API要特别注意不要把高权限、长期有效的 API Key 直接写进公开前端源码。更安全的做法通常是浏览器前端 → 你的后端服务 → 第三方 API由后端统一保存密钥、发起请求、做权限控制和日志脱敏。5.3 Python requests 示例import requests response requests.get( https://api.example.com/v1/users, headers{Authorization: fBearer {api_key}} )同样api_key变量里通常只保存 key 本身。如果你要排查是否读取到了环境变量可以打印长度或前后几位但不要打印完整 token。例如只做安全检查print(len(api_key))不要在日志里直接输出print(api_key)5.4 Postman 里怎么填如果你在 Postman 里选择Auth Type: Bearer Token那么 Token 栏只填xxx不要填Bearer xxx因为 Postman 会自动生成Authorization: Bearer xxx如果你是在 Headers 里手动填写则写完整的Authorization: Bearer xxx这两种方式不要混用。否则很容易变成Authorization: Bearer Bearer xxx6. Bearer Token、API Key、Access Token、JWT 的区别这几个词经常被混在一起用但它们其实不在同一个维度上。名称它是什么是否一定要加 Bearer常见场景API Key服务商发给调用方的密钥不一定看 API 文档SaaS API、AI API、支付 API、地图 APIBearer Token一种“持有即可使用”的访问凭证或认证方式通常通过Bearerscheme 发送API 认证、OAuth 2.0、服务间调用Access Token授权服务器签发的访问令牌很多情况下是 BearerOAuth 2.0、第三方登录、开放平台JWT一种 token 格式可以作为 Bearer Token 使用登录态、微服务认证、网关鉴权可以这样理解API Key 可以通过 Bearer 的方式提交OAuth Access Token 经常是 Bearer TokenJWT 可以被当作 Bearer Token 使用Bearer Token 不一定是 JWTBearer Token 不一定来自 OAuthAPI Key 也不一定必须写成Authorization: Bearer xxx。所以不要简单地说Bearer Token 一定比 API Key 更安全安全性要看更具体的设计例如是否使用 HTTPS是否有过期时间是否支持撤销权限范围是否足够小是否会被写进日志是否暴露在前端代码里是否支持定期轮换。7. 服务端通常如何解析 Bearer Token服务端处理 Bearer Token 时一般会经历这些步骤读取 Authorization 请求头 ↓ 判断是否以 Bearer 开头 ↓ 截取 Bearer 后面的 token ↓ 校验 token 是否存在或签名是否正确 ↓ 检查是否过期、是否撤销、权限是否足够 ↓ 通过则继续处理请求 ↓ 失败则返回 401 或 403如果 token 是一串随机字符串服务端一般需要到数据库或缓存里查询。如果 token 是 JWT服务端可能会验证签名过期时间issueraudiencescope自定义声明字段。这里最关键的一点是Bearer 只负责标识认证方式真正决定权限的是后面的 token以及服务端如何校验它。8. 为什么不建议把 token 放在 URL 里有些 API 允许这样传 keyGET /v1/users?api_keysk-xxxx但一般不建议把 Bearer Token 或 API Key 放在 URL query 参数里。原因是 URL 太容易被记录和传播。常见风险包括浏览器历史记录可能保存完整 URL服务端访问日志可能记录 query 参数代理、网关、监控系统可能采集 URL某些跳转场景下URL 可能通过 Referer 泄露URL 被截图、复制、分享的概率更高。相比之下Authorization请求头本来就是 HTTP 中放认证信息的标准位置更适合被 API 网关、中间件、SDK 和安全工具统一处理。很多日志系统也更容易对Authorization头做脱敏。所以除非服务商文档明确要求否则更推荐Authorization: Bearer xxx而不是?tokenxxx9. 常见报错排查为什么加了 Bearer 还是 401如果调用 API 时返回401 Unauthorized或者403 Forbidden可以按下面顺序排查。错误写法或问题可能后果正确做法Authorization: Bearer: xxxHeader 格式错误写成Authorization: Bearer xxxAuthorization: xxx服务端识别不到 Bearer scheme按文档加上BearerAuthorization: Bearer Bearer xxx重复前缀只保留一个BearerBearer后面没有空格服务端解析失败Bearer和 token 中间保留空格Postman Token 栏填了Bearer xxx可能生成重复 BearerToken 栏只填xxxtoken 放在 query 里服务端可能不读取放入Authorization请求头token 已过期返回 401重新获取或刷新 tokentoken 权限不够返回 403检查 scope、角色和资源权限环境变量读错实际传了空值或旧值打印长度或前后几位排查不要打印完整 tokenAPI 要求X-API-KeyBearer 方式无效严格按服务商文档传9.1 401 和 403 的区别通常可以这样理解401身份认证没通过 403身份知道了但权限不够常见401原因没传 tokentoken 写错token 已过期Bearer 格式错误环境变量没读取到请求打到了错误 Endpoint。常见403原因token 有效但没有访问该资源的权限scope 不够角色权限不够当前 key 不允许调用某个模型或接口服务端策略拒绝访问。不过不同服务商实现可能不同最终仍要以接口返回内容和官方文档为准。10. 验证 Bearer Token 配置是否正确配置完成后建议按下面步骤验证。10.1 先确认环境变量是否读取成功例如在本地 shell 中echo $API_KEY如果担心泄露不建议直接打印完整 key可以只检查长度或是否为空。在程序里可以检查API_KEY 是否为空 API_KEY 是否多了 Bearer 前缀 API_KEY 是否包含多余空格或换行尤其要注意从控制台复制 key 时可能会带上不可见字符。10.2 再确认请求头最终长什么样最终请求头应该类似Authorization: Bearer abc123不是Authorization: Bearer: abc123也不是Authorization: Bearer Bearer abc123如果使用 SDK 或工具要确认它是否已经自动加了Bearer。10.3 再确认 Endpoint 和路径如果你接的是 API 网关或兼容接口要确认Base URL 是否正确 请求路径是否正确 协议是否为 HTTPS 是否走了正确代理 容器或部署环境是否读取了同一份配置10.4 最后确认模型名和权限如果鉴权通过但仍然失败再检查模型名是否正确 当前 key 是否有权限访问该资源 请求体格式是否符合接口要求这样排查会比一上来反复换 token 更高效。11. Bearer Token 安全使用建议Bearer Token 最大的风险是谁拿到谁就可能使用所以安全措施不能只停留在概念上最好落实到具体操作。建议至少做到始终使用 HTTPS避免 token 在传输过程中被窃听不要把 token 放在 URL query 参数里不要把 API Key 或 token 提交到 Git 仓库使用.env、密钥管理服务或平台提供的 Secret 配置不要在日志里打印完整 token对日志中的Authorization头做脱敏给 token 设置过期时间尤其是用户授权类 token长期 API Key 要支持定期轮换遵循最小权限原则只授予必要 scopetoken 泄露后要立刻撤销并重新生成浏览器端不要暴露高权限、长期有效的服务端密钥服务端校验时检查签名、过期时间、撤销状态和权限范围。如果你是在后端调用第三方 API一般可以把 API Key 放在服务端环境变量中。如果你是在前端页面直接调用就要格外小心任何写进前端代码的 key理论上用户都有可能看到。12. FAQ12.1Bearer是必须写的吗不一定。只有 API 文档要求使用Authorization: Bearer xxx时才必须这样写。有些 API 可能要求X-API-Key: xxx也有的会使用Authorization: Basic xxx或者其他自定义认证方式。核心原则是按 API 文档传。12.2Bearer大小写敏感吗从 HTTP 认证规范角度看认证方案通常不强调大小写。但在实际工程里建议严格按文档写成Bearer这样可以避免某些服务端实现不够规范导致解析失败。12.3 API Key 和 Bearer Token 是一回事吗不是一回事。API Key 是凭证本身。Bearer Token 更强调一种“持有即可使用”的凭证用法或认证方式。一个 API Key 可以被设计成通过 Bearer scheme 来提交。12.4 JWT 一定是 Bearer Token 吗不一定。JWT 是一种 token 格式。Bearer 是一种提交凭证的认证方案。JWT 可以放在下面这种请求头中使用Authorization: Bearer jwt但 JWT 本身不等于 Bearer。12.5 Postman 里 Bearer Token 应该填什么如果 Auth Type 选的是Bearer TokenToken 栏只填 token 本身xxx不要填Bearer xxx只有在 Headers 里手动填写时才写完整的Authorization: Bearer xxx12.6 Bearer Token 可以放 Cookie 吗技术上可以把某些 token 放在 Cookie 里。但这属于另一套认证设计会涉及SameSiteHttpOnlyCSRF 防护Cookie 作用域跨域策略。调用开放 API 时更常见的做法还是按文档放在Authorization请求头中。12.7 为什么有的 API 用X-API-Key有的用Authorization: Bearer这主要是服务商的接口设计选择。Authorization: Bearer更符合标准 HTTP 认证位置方便网关、中间件和 SDK 统一处理。X-API-Key更直观常见于简单 API Key 鉴权。两者没有绝对好坏关键是按文档传并保护好密钥总结Bearer Token 的核心并不复杂API Key / token 是凭证本身 Bearer 是提交凭证的认证方式 Authorization 是放认证信息的 HTTP 请求头正确格式是Authorization: Bearer token排查 API 鉴权问题时优先检查Bearer后面是否有空格是否多写了冒号是否重复写了Bearer环境变量里保存的是不是 token 本身Endpoint 是否正确模型名和权限是否匹配API 文档是否要求使用其他 Header。对于 Claude Code、Anthropic API 或兼容网关接入场景重点不是“看到 API Key 就一定加 Bearer”而是确认当前服务端要求的鉴权格式。