团队用 Claude API 之前要管好的事：key 的类型、工作区、限额、用量花费和数据保留

这篇教程解决一组“上了规模才会遇到”的问题：key 该给人还是给服务？开发和生产怎么隔开？这个月的钱花在了哪个项目上？有人离职了，他的 key 怎么办？发给接口的数据会被存多久？

先说清楚适用范围。 本文讲的全是 Claude 官方控制台（Claude Console）里组织一级的功能。它们对两类读者有用：公司有官方账号、直连官方接口的团队；以及想弄明白这套东西是怎么设计的人。

如果你是通过中转站在用，这些功能用不到：中转站发给你的 key、你看到的用量和账单，都是中转站自己的系统。本站在酷站AI 中转站上做了探测，结果如下：

探测	结果
组织、用量、花费、限流、工作区这五个管理接口	全部 404
普通响应里有没有工作区和组织的响应头	没有，只有一个 `x-request-id`
请求里带一个不存在的工作区 ID	被忽略，返回 200

所以本文全部按官方文档整理，没有实测。

一、三种认证方式

方式	凭据	适合
API key	一串固定的密钥	本地开发、脚本、你能管好密钥存放的服务器
工作负载身份联合	用你已有的身份提供方签发的短期令牌去换一个短期的访问令牌	云上的生产服务、CI、Kubernetes，目标是环境里不留长期密钥
App Attest	发给一台设备上真实安装的应用的短期令牌	分发给最终用户、直接从设备调接口的 iOS 和 macOS 应用

前两种能访问的接口相同。文档的建议是从 API key 起步；等服务本来就有平台签发的身份（比如 GitHub Actions、云厂商的角色）时，换成身份联合，把长期密钥从环境里拿掉。

App Attest 的令牌一小时过期，只能调消息接口，用量记在你的工作区名下。

二、API key 分三种

创建 key 的时候要选类型。它决定这把 key 代表谁、能在哪用、什么时候失效：

类型	代表谁	什么时候失效
个人 key	你本人，带着你的角色和权限	你被移出组织（或移出那个工作区）时
服务账号 key	一个服务账号	服务账号被归档（或被移出那个工作区）时。创建它的人离开不影响
工作区 key（旧式）	不代表任何人，属于创建它的那个工作区	过期、被停用或删除、工作区被归档时。创建者离职它照样能用

前两种是“有主”的：背后是组织里一个真实的人或服务账号，身份没了 key 就停。新的集成优先用这两种，这样 key 不会比它的主人活得更久。

自己开发、跑脚本：个人 key。把个人 key 给别人共用，等于大家都在冒充一个人，那人一走全断。
CI、线上服务这类多人共用或无人值守的：让组织管理员建一个服务账号，用服务账号 key。
旧式的工作区 key 还能用，文档建议逐步换掉。

用和管

请求头用 Authorization: Bearer <key>。旧的 x-api-key 请求头仍然支持。SDK 读环境变量 ANTHROPIC_API_KEY。
过期时间在创建时选：3 小时、1 天、7 天、30 天、自定义，或者永不过期。组织可以设一个最长期限，设了以后就不能选“永不”。
有效期在 14 天以上的 key，到期前 7 天会给创建者发邮件；7 天以上的，前 1 天发。更短的不提醒。
过期后请求返回 401，过期的 key 不能恢复，只能新建。
停用可以恢复，删除不能。
放进密钥管理服务，定期轮换；怀疑泄露就立刻停用或删除。过期时间只是缩短了泄露之后的窗口，不能代替这些做法。

一把 key 用在多个工作区

创建时把 key 限定在一个工作区，它就只能在那里用，请求里什么都不用加。没有限定的 key 可以用在多个工作区，但每个请求都要带上工作区：

anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

不带这个头返回 400；ID 格式不对返回 400；工作区不存在或没有权限返回 404。

三、工作区：把环境、团队、项目隔开

工作区是组织下面的一层划分。每个工作区有自己的成员、key、限额和用量统计，账单和管理仍然归在组织一级。

每个组织有一个默认工作区，不能改名、归档或删除。
默认最多 100 个工作区，归档的不算。
工作区的 ID 以 wrkspc_ 开头。

常见的三种分法：

分法	例子
按环境	开发、预发、生产各一个。开发用低一些的限额
按团队	工程、数据、客服各一个，方便分摊费用和控制权限
按项目或产品	一个产品一个，单独看用量和花费

哪些东西是按工作区隔离的： 每个请求只在一个工作区里运行，只能碰那个工作区里的资源。通过 Files API 上传的文件、批量任务、上传的 skill，都属于创建它们的工作区，并且对整个工作区可见。所以多租户的应用要一个租户一个工作区，前几篇里提过。

角色：

工作区角色	能做什么
用户	只能用控制台里的试验场
受限开发者	创建和管理 key、调接口；不能看会话追踪、不能下载文件
开发者	创建和管理 key、调接口
管理员	管理工作区的设置和成员
账单	看工作区的账单。不能手动指派，由组织的账单角色继承而来

组织的管理员自动是所有工作区的管理员。组织里的普通用户和开发者要一个一个加进工作区。

限额： 每个工作区可以单独设每月的消费上限和限流（每分钟请求数、输入 token、输出 token），只能比组织的低，不能更高。默认工作区不能单独设限流。

归档不可逆。 归档一个工作区会在几秒内把为它创建的 key 全部归档，历史数据保留供查账。

Claude Code 工作区

组织里第一次有人用控制台账号登录 Claude Code 时，会自动出现一个名叫 Claude Code 的工作区，之后每个登录的人都会被加进去。它的作用是把 Claude Code 的流量和别的接口用量分开：

登录时 Claude Code 在这个工作区里给每个人生成一把 key。不能在控制台里手动往这个工作区建 key。
这把 key 跟人走：人被移出工作区或组织，key 就失效。
Claude Code 的用量单独限流，管理员可以限制它占组织总限额的比例。
它是唯一支持“每人每月消费上限”的工作区。
把它归档，整个组织就不能再用控制台账单登录 Claude Code。

一个响应是哪个工作区的

官方接口的每个响应都带一个 anthropic-workspace-id 响应头，值是这次请求实际落在的工作区，默认工作区也会给出。拿它可以确认用量记在了哪里，或者和用量报告里的 workspace_id 对账。要注意：用量报告和 key 的信息里，默认工作区的 workspace_id 显示为 null。

四、Admin API：用程序管成员、工作区和 key

控制台里手动做的那些事，Admin API 都能用程序做：管组织成员和角色、发邀请、建工作区、管工作区成员、查看和停用 key。典型用途是入职离职自动化和定期审计 key。

个人账号用不了 Admin API，要先在控制台里建组织。

它接受三种凭据：

凭据	谁能拿到
Admin API key，以 `sk-ant-admin01-` 开头，放在 `x-api-key` 请求头里	只有组织的管理员能创建
带 `org:admin` 范围的 OAuth 令牌	管理员、所有者
没有限定工作区的个人 key 或服务账号 key	权限等同于它背后的账号

旧式的工作区 key 不行。Admin API key 没有可选的权限范围，一把就是全部，而且完整的密钥只显示一次。

组织一级有五种角色：

角色	能做什么
user	用试验场
claude_code_user	用试验场和 Claude Code
developer	用试验场，管理 key
billing	用试验场，管理账单
admin	以上全部，外加管理成员

一个容易想错的地方：Admin API 不能创建 API key。 key 只能在控制台里建，Admin API 只能读、改名、改状态。

SDK 里这组接口在 client.organization 下面，命令行是 ant organization。

五、查用量和花费

控制台的用量页和花费页，背后有两个接口可以直接调，都要用上一节的管理凭据。

用量接口按时间桶返回 token 数：

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-10-06T00:00:00Z&\
ending_at=2026-10-13T00:00:00Z&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

桶的宽度	默认返回	最多	适合
`1m`	60 个	1,440 个	实时监控
`1h`	24 个	168 个	看一天里的规律
`1d`	7 个	31 个	周报、月报

token 分四类统计：没走缓存的输入、缓存读、缓存写、输出。可以按 key、工作区、模型、服务档位等过滤和分组。服务器端工具（比如联网搜索）的次数也在这里。

花费接口（/v1/organizations/cost_report）返回美元金额：

金额是字符串，单位是美分。
只有按天这一种粒度。
可以按工作区或按费用说明分组。
包含 token、联网搜索、代码执行的费用。

几个文档特意说明的细节：

数据延迟一般在 5 分钟以内。 持续轮询的话每分钟一次。
默认工作区的 workspace_id 是 null。
控制台试验场里的用量没有对应的 key，api_key_id 是 null。
代码执行只出现在花费接口里，用量接口里没有。
优先档位（Priority Tier）的花费不在花费接口里，要在用量接口里按服务档位看。
想看 Claude Code 每个人花了多少，用下面第七节的接口，不要靠“每人一把 key 再分组”去凑。

这两个接口的用处，文档列了几条：和财务对账、按工作区分摊成本、量缓存的命中效果、做预算告警。也有现成的第三方可观测性平台接了它们。

六、读限流的配置

限流接口返回的是配置的上限，不是当前用了多少：

import anthropic

client = anthropic.Anthropic()          # 读环境变量里的管理凭据

for entry in client.organization.rate_limits.list():
    models = f" ({', '.join(entry.models)})" if entry.models else ""
    print(f"{entry.group.type}{models}")
    for limit in entry.limits:
        print(f"  {limit.type}: {limit.value}")

要点：

限流是按组算的：几个模型版本共用一组上限。另外有批量、文件、token 计数、skill、联网搜索这几个组。
每个组里是若干条上限：每分钟请求数、每分钟输入 token、每分钟输出 token。
想知道某个模型属于哪个组，把模型名传给 model 参数。
工作区的接口默认只返回这个工作区单独设过的上限；没出现的就是沿用组织的，不是“不限”。加 include_inherited=true 可以一次看全。

文档说的用途：网关和代理启动时读一遍，定时刷新，不要把限额写死在代码里；和用量接口的数据一比，就能做“快到限额了”的告警。

限流本身怎么算、撞上了怎么办，见《报错、限流和停止原因》。

七、Claude Code 的使用分析

给团队买了 Claude Code，想知道大家用得怎么样，有一个专门的接口。它按“每人每天”返回数据：

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?\
starting_at=2026-10-12&\
limit=20" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

每条记录是一个人一天的情况，包括：

会话数；
Claude Code 增加和删除的代码行数；
通过它创建的提交数和 PR 数；
各个编辑类工具的提议被接受和被拒绝的次数；
按模型分的 token 用量和估算的花费；
用的是什么终端。

starting_at 是一个日期，一次只查一天。数据最多延迟一小时。这个接口免费，有管理凭据就能调。

这是控制台组织用的接口。用 claude.ai 的企业版的组织，要用另一套企业分析接口和另一种 key，两种 key 不通用；那套接口还提供全组织的活跃用户、各产品的使用情况，以及按用量计费的企业版的花费报告。

八、每人的消费上限（只有企业版）

消费上限接口只对 claude.ai 的企业版组织开放，控制台组织用不了，这里只说它是什么：

可以读每个成员当前生效的上限、这个上限是从哪一层继承来的（个人、席位档、用户组、组织默认）、本周期已经花了多少。
可以给某个人单独设上限，或者清掉。
成员在产品里点“申请更多用量”会产生一条申请，可以用接口批准或拒绝。
周期目前只有按月一种，每月 1 日零点（UTC）清零。金额是字符串，单位是最小货币单位（美元就是美分）；null 表示不限，"0" 表示不能超出套餐自带的用量。

控制台组织要限制花费，用第三节说的工作区消费上限。

九、发给接口的数据会留多久

默认的承诺有三条：

留存的数据不会在没有你明确许可的情况下用于训练模型。
只留功能运行在技术上必需的东西。对话内容（你的提示词和模型的输出）默认不留存。
留存的数据按尽可能短的期限清除。

在这之上有两种专门的安排，都要另外申请或开通。

零数据保留（ZDR）：响应返回之后，Anthropic 不再存你的提示词和输出。按组织开通，要联系销售。它覆盖什么、不覆盖什么，文档有一张按功能列的表，下面是和这个系列相关的部分：

功能	是否在 ZDR 范围内
消息接口、token 计数、思考、effort、流式	是
提示词缓存、引用、搜索结果块、PDF、对话中途的系统消息	是
bash、文本编辑器、记忆、电脑和浏览器操作（都在你这边执行）	是
联网搜索、抓取网页、工具搜索、顾问、压缩、上下文编辑	是
结构化输出	是，但有保留：schema 编译出的语法会缓存最多 24 小时
代码执行、程序化调用工具	否，容器数据最多保留 30 天
Files API	否，文件保留到你删除为止
批量处理	否，保留 29 天
skill、MCP 连接器、托管智能体	否

三点容易忽略：

不在范围内的功能，ZDR 组织照样能调，接口不会拦。 用不用要你自己把关。
联网搜索和抓取网页的新版本默认带动态过滤，动态过滤靠代码执行，所以默认不在范围内；要在范围内，得给工具加上 allowed_callers: ["direct"] 关掉它，见《服务器端工具》。
Fable 和 Mythos 这几个模型要求保留 30 天，默认不能在 ZDR 下使用。有 ZDR 的组织可以单独给某个工作区打开 30 天保留，只在那个工作区里用这些模型。

另外，控制台里的使用（包括试验场）、个人版的各种套餐，都不在 ZDR 范围内。用 API key 的 Claude Code 在范围内；如果开了指标上报，使用统计这类数据不在。

HIPAA：处理受保护健康信息的组织，签了相应的协议并开通之后，可以用列表里符合条件的功能。和 ZDR 相反，不符合条件的功能在这类组织上会被接口直接拒绝（400）。一旦开通不能关闭，所以文档建议需要两种用途的话分成两个组织。还有一条和前面几篇有关：不要把这类敏感信息写进 JSON Schema（字段名、枚举值、正则），因为 schema 是单独缓存的，受到的保护和消息内容不一样。

最后一条不分安排都适用：法律要求保留的，或者被自动安全系统标记的内容，仍然可能被保留。

十、用一个 HTTP 请求触发 Claude Code 的例程

这一页放在平台文档里，但它属于 Claude Code 这个产品，和上面的内容是两套体系。

例程（routine）是存在 Claude Code 网页版里的一份配置：一段提示词、一个或几个仓库、若干连接器，可以无人值守地运行。它有一个 HTTP 入口，告警系统或 CI 可以调它来启动一次运行：

curl -X POST https://api.anthropic.com/v1/claude_code/routines/$ROUTINE_ID/fire \
  -H "Authorization: Bearer $ROUTINE_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "生产环境的告警 SEN-4521 触发了，堆栈见下。"}'

它和平台接口的区别：

	触发例程	平台接口
认证	每个例程单独的令牌，在 Claude Code 网页版里生成	控制台里的 API key
令牌能做什么	只能触发这一个例程，没有任何读取权限	工作区一级
计费	记在 claude.ai 的 Claude Code 订阅用量里	平台用量
SDK	没有	有
稳定性	实验性，格式可能变	稳定或标准 beta

要知道的事：

需要 Pro、Max、Team 或 Enterprise 套餐，并且开了 Claude Code 网页版。
请求体里只有一个可选的 text，最长 65,536 个字符，作为这次运行的附加上下文。它不会被解析，发 JSON 过去也是当成一段文字。
请求在会话建好后就返回会话的 ID 和网址，不等它跑完，也不流式返回输出。
没有幂等机制。 调用方重试一次，就多建一个会话。
每个例程每小时最多触发 30 次，每个账号每小时最多 100 次。超了返回 429，带 Retry-After。
令牌只显示一次；重新生成会让旧的失效。

例程本身怎么建，见《云端会话》里关于定时和事件触发的部分。

上线前可以对照的清单

把上面的内容收成几条：

线上服务用服务账号 key 或身份联合，不用个人 key，更不要多人共用一把。
开发、预发、生产分开工作区；生产的 key 限定在生产工作区。
给每个工作区设消费上限和限流。
key 设过期时间，放进密钥管理服务，有轮换的流程。
有人离职时，他的个人 key 会随账号失效；检查有没有他建的旧式工作区 key 还在用。
定期用 Admin API 列一遍 key，看过期时间和状态。
用量和花费按工作区看，接进自己的监控或者每周出一份。
上传的文件、批量任务、skill 对整个工作区可见，多租户要分工作区。
弄清楚用到的功能里哪些会留存数据（代码执行、文件、批量、skill），是否符合你们的合规要求。

没有实测的部分

全文没有实测。 本站没有官方组织的管理凭据，所有接口、限制和数字都来自官方文档。
示例里的请求没有运行过，是按文档的示例改写的（日期换成了近期的）。
中转站一侧只做了开头那三项探测。 中转站自己怎么管 key、怎么计费、数据怎么留存，不在本文范围内，以它自己的说明为准。
企业版的接口（企业分析、消费上限）只做了简单介绍。
身份联合和 App Attest 的配置步骤没有展开，官方各有专门的文档。