API 密钥
带作用域的密钥，允许外部系统代表你调用 Carbon API，并拥有自己的权限。
用于认证对 Carbon 的程序化请求。每个密钥属于一家公司，并拥有独立于创建者的显式权限作用域。在设置 → API 密钥中管理。
连接器不需要密钥
Claude.ai、Claude Desktop 和 ChatGPT 通过 OAuth 连接。连接继承授权用户的角色和公司。对于没有浏览器 OAuth 的客户端（包括 Claude Code、Cursor、VS Code、Codex、无头脚本和 CI），请使用 API 密钥。仅支持 stdio 的客户端通过 mcp-remote 连接。两种流程参见认证。
创建密钥
选择 New API Key（新建 API 密钥），输入公司内唯一的名称，可选设置 Expires At（到期时间），授予作用域并保存。到期留空表示密钥不过期。Carbon 只显示一次完整密钥，之后仅保存其 SHA-256 哈希和五字符预览。请立即复制；如果丢失，请删除并重新创建。对话框还提供 MCP 连接命令。
密钥是持有者密钥
任何持有密钥的人都能在其作用域内以其身份操作。请保存在密钥管理器中，绝不要提交到仓库；若泄露请轮换（删除并重建）。
认证请求
将密钥作为 Bearer 令牌发送；托管数据 API 位于 rest.carbon.ms：
GET /salesOrder?select=id,salesOrderId,status
Host: rest.carbon.ms
Authorization: Bearer crbn_your_key_hereAPI 密钥无需登录或刷新流程。Carbon 会对提交的密钥做哈希，并在处理请求前检查其记录、到期时间和限流。
边缘使用 Bearer，底层使用 carbon-key
rest.carbon.ms 接受 Authorization: Bearer crbn_…，并在内部以 carbon-key 请求头转发令牌。在自托管安装上直接调用 PostgREST 时，请向 /rest/v1/<table> 发送 carbon-key: crbn_…。MCP 端点在两种部署中都接受 Bearer 令牌。
作用域与限流
密钥只拥有其存储的 module_action 作用域（例如 sales_view 或 inventory_create），并且只能访问其公司。没有作用域的密钥可以认证，但无法读写数据。作用域变更和删除立即生效。在 Carbon Cloud 上，API 访问需要 Business 套餐；Starter 套餐的请求无论作用域如何都返回 403。参见许可。
新密钥允许每分钟 20 个请求。现有密钥保留 Rate Limit（限流） 列中显示的限额。公司的所有密钥共享另一个每分钟 60 个请求的限额。这两个限额都不能在 Carbon 中修改。如果集成需要更多，请联系 Carbon 支持：可以为一公司提高两个限额。被拒绝的请求返回 429 和 Retry-After、X-RateLimit-* 响应头；请在指定间隔后重试。
密钥解锁什么
默认使用 Carbon API。它会校验输入、更新派生数据，并通过 Carbon 服务层执行权限。每个操作在 HTTP 上通过 POST /api/v1/{module}/{operation}、通过 MCP 接受相同参数。操作被分类为 READ、WRITE 或 DESTRUCTIVE，以便客户端按风险把关。参考文档包含示例以及用于生成客户端 SDK 的 OpenAPI 规范。
数据 API在应用的行级安全策略下提供对表和视图的直接 REST 访问。
数据 API 在服务层之外
数据 API 写入绕过服务层，不会重新计算合计、状态或台账分录等派生值。只有当 Carbon API 未提供所需操作且你了解所有受影响数据时，才使用直接写入。
密钥与 Webhook
API 密钥授权对 Carbon 的请求。Webhook在订阅记录变更时通知你的服务。两者相互独立：Webhook 用自己的签名密钥签名，绝不用 API 密钥。典型集成把 Webhook 作为变更通知，然后用 API 密钥获取当前记录。