定时发送程序应在配置它的员工离职后继续运行。而代表该员工操作的工具则需要遵循其权限的访问方式。
根据这一归属关系选择凭据。不要将任何凭据暴露在浏览器代码或日志中，因为持有凭据的任何人都可以尝试发起已认证的请求。
每种凭据能做什么？
API 密钥代表工作区操作。OAuth 令牌让授权工具代表个人操作。
Bird API 密钥以 bk_ 开头。其权限属于工作区，因此移除创建者不会使其失效。仅授予服务所需的作用域，以限制密钥泄露后的影响范围。
密钥无法执行组织级操作，例如管理组织成员或账单。增加更多工作区作用域不会移除这一限制。
当你通过 CLI 或 MCP 服务器登录时，你将授权工具使用你的部分权限。工具会收到一个短期的 bt_ 令牌。令牌续期由工具管理，因此不要将该令牌复制到服务的密钥管理器中。
通过 Profile > Connected apps 吊销已授权的工具。使用身份验证来选择作用域，并区分工作区密钥与个人授权。
如何轮换 API 密钥？
签发替代密钥，并在旧密钥的重叠期结束前完成部署。
你可以从仪表板、通过 bird api-keys rotate 或通过 api_keys_rotate MCP 工具进行轮换。CLI 和 MCP 轮换需要具有 api_keys:write 的个人授权。API 密钥无法持有该权限，也无法轮换其他密钥。
轮换操作仅返回替代密钥的 token 一次。请立即保存，因为之后无法再次获取。替代密钥保留旧的名称和 IP 限制。除非你提供新的 scopes，否则权限也会保留。
设置 grace_period 来控制重叠期。其默认值为 24h，因此请在一天内完成部署。旧密钥上更早的过期时间仍然适用，轮换不会延长它。
当泄露的密钥需要立即吊销时，使用 grace_period: "0"。缓存验证仍可能在短时间内接受该密钥，详见下文。
- 请求轮换并保存返回的令牌。
- 在重叠期结束前将替代密钥部署到每个服务。
- 通过服务日志确认使用替代密钥的请求已成功。
- 等旧密钥过期，或在切换完成后将其吊销。
轮换参考涵盖了该命令及其选项。
轮换过程中可能出什么问题？
响应丢失可能导致替代密钥已签发但你从未保存其令牌。
重试轮换请求时使用相同的 Idempotency-Key，以便 Bird 重放其响应。一个密钥只能轮换一次。如果没有使用相同的幂等键，重复轮换将返回 409。对替代密钥执行轮换可用于后续的计划变更。
已吊销的密钥无法轮换。如果原密钥已被吊销，请创建新密钥。
替代密钥没有过期时间，即使原密钥有。你无法在事后添加过期时间。当密钥必须在已知时间停止工作时，请使用 expires_at 创建新密钥。
对于部署时长不确定的情况，创建第二个密钥并自行管理重叠期。在吊销原密钥之前部署新密钥。轮换的宽限期在请求发出后无法延长。
吊销多快生效？
已吊销的密钥在缓存验证过期期间，最多五秒内仍可能被接受。
在该窗口期内，应将泄露的密钥视为仍可使用。吊销是永久性的，已吊销的密钥无法重新激活。Bird 会保留其记录以供审计。
在与支持团队沟通时，使用 key_prefix 或 fingerprint 来标识密钥。切勿包含完整凭据，因为这些标识符足以区分密钥而不会授予访问权限。
应该选择哪种凭据？
根据谁拥有工作负载以及所需的权限来选择。
- API 密钥: 需要独立于创建者持续运行的服务。
- OAuth 授权: 在个人权限范围内操作的 CLI 或代理。
- 轮换: 可在已知重叠期内部署的替代密钥。
- 带过期时间的新密钥: 必须在特定时间停止工作的凭据。
简而言之
服务凭据属于工作区。
密钥在其创建者离开后仍然有效。使用 OAuth 的工具在授权者的权限范围内操作。
在轮换重叠期内完成部署。
旧密钥默认在 24 小时内继续有效，除非其现有过期时间更早。
在签发时立即保存替代密钥。
轮换操作仅返回新令牌一次。如果需要重试轮换请求，请使用相同的幂等键。
吊销存在短暂的传播窗口。
缓存验证可能在最多五秒内仍接受已吊销的密钥，因此在泄露后需考虑这一延迟。