什么是 API Key

它解决什么问题

服务端要回答三个问题：你是谁、该记谁的账、给你多少额度。

在没有人登录的机器调用场景里，账号密码不合适——它需要人交互，权限也太大。API Key 把这三件事压成一串字符：请求带上它，服务端查表就知道对应哪个账号、哪个分组、什么权限。

一次调用里它经过哪几步

1. 客户端把 key 放进请求头（常见 Authorization: Bearer … 或 x-api-key）。
2. 网关拿它查账号、权限、余额、分组倍率。
3. 通过就转发给模型，同时记一笔用量。
4. 任何一步对不上，就在这一步返回 401 或 403，请求不会到模型。

所以 401 几乎总是发生在第 2 步——这也是为什么「换把新 key」只在 key 本身失效时有用。

一个最小例子

export DOCAI_API_KEY="sk-..."   # 只存在当前 shell 会话里
curl https://api.example.com/v1/models \
  -H "Authorization: Bearer $DOCAI_API_KEY"

不要把 key 写进代码、提交到仓库，或粘进会保存历史的命令行。泄露之后，正确做法是立刻吊销再新建，而不是改密码。

三个常见误解

• 「key 就是密码，存数据库里加密一下就行」：不行。服务端需要原文比对，所以泄露即等同于账号被用；只能靠吊销和最小权限控制损失。
• 「一把 key 能调所有模型」：不一定。key 绑在账号或分组上，模型权限、地区、额度都可能单独限制。
• 「401 都是 key 错了」：不是。key 失效、请求头格式错、账号被封、地区不支持，都可能表现成 401/403。分情况的判断见 API key 没错却一直 401。

和相邻概念的区别

对比	API Key	OAuth 令牌	账号密码
代表谁	一个调用方/服务	某个用户授权的结果	一个人
有效期	长期，手动轮换	短，可刷新	长期
权限范围	由账号与分组决定	由授权范围决定	全量
泄露后	吊销重发	撤销授权	改密码（且可能已被撞库）

延伸阅读

• API 本身是什么：什么是 API
• 亲手发一次带鉴权的请求：第一次 API 调用
• 401/403 的分情况排查：API key 没错却一直 401