API 密钥

API 密钥让脚本或另一个系统在没有人登录的情况下对你的工作区做事。

创建

设置 → API 密钥 → 新建密钥。 起一个说明"谁会用它"的名字——nightly-order-export，不是 key1——因为一年后你判断它还需不需要时，名字是你唯一能依据的东西。

密钥只在创建时显示一次。它以哈希形式存储，所以任何人（包括我们）都无法再次显示它。弄丢了就等于要新建一个并吊销旧的。

密钥形如 juno_live_…。前十四个字符以明文保留，纯粹是为了让列表能区分哪个是哪个；其余部分从不存储。

使用

作为 bearer token 发送：

Authorization: Bearer juno_live_4f2a…

工作区来自密钥本身，不来自你发送的任何内容——每个请求都被限定在这个密钥所属的工作区里，没有任何办法访问另一个。

一个密钥能做什么

密钥不可能比创建它的人更有权限。 它的权限是"你申请的"和"你自己持有的"两者的交集，所以一个 Agent 无法造出一个管理员。

申请能跑通的最窄的那一套。 一个用来导出联系人的密钥需要 contact.view，别的都不要；一个只负责发消息的密钥不需要读消息的权限。

密钥作为机器主体行事——它没有用户、没有成员关系。任何需要一个"人"的操作（改密码、接受邀请）对它都不可用。

吊销

在密钥所在行点吊销。立即生效，你这边不需要重启任何东西，用它发的请求会返回 401。

吊销而不是删除：行还在，所以审计记录仍然能说清是哪个密钥做了什么。

三个值得吊销的时刻：

• 密钥被粘到了不该粘的地方——代码仓库、工单、截图。
• 它服务的那个集成被关掉了。 一个没人用的密钥只剩风险。
• 有 api_key.create 权限的人离职了。

值得养成的习惯

• 一个集成一个密钥。 一个共用的密钥没法在不弄坏所有东西的前提下吊销，所以它永远不会被吊销。
• 绝不放进客户端。 放在浏览器或移动 App 里的密钥就是公开的密钥，不管怎么混淆。网页挂件存在的意义正是让页面不需要密钥。
• 看"最后使用"。 几个月没人用过的密钥，就是该吊销的密钥。
• 在不得不轮换之前轮换。 先建新的、把集成切过去、再吊销旧的——按这个顺序，中间任何一步都不会断。