API 密钥
选择个人或服务权限,保存仅显示一次的密钥值,并在更换凭据时清楚掌握哪些调用方仍在使用它们。
API 密钥让调用方能够在指定权限范围内执行操作。个人密钥的权限随个人的成员身份和权限而变化。组织服务密钥归组织所有,让自动化流程不受某位同事离职的影响。启用 RBAC 后,服务密钥还可以拥有独立的角色和资源范围。
密钥值仅在创建时显示,之后无法从密钥记录中找回。请立即将其保存到密钥管理器或调用方支持的凭据存储中。切勿将其放入源文件、已提交的配置、截图或客服沟通消息中。
以个人身份开展工作时,使用个人密钥 #
在所选组织的设置 → API 密钥 → 个人中,创建个人密钥并命名。成员可以为自己创建密钥。密钥的权限取决于创建者当前的成员身份和实际生效的权限;与服务密钥不同,个人密钥无法单独分配角色,也无法按本地化引擎设置访问范围。
个人密钥适用于代表操作者执行操作的本地调用方。如果成员离开组织或失去权限,密钥的访问权限也会随之变化。如果组织的自动化流程不应依赖某个人持续拥有访问权限,请使用服务密钥。
创建服务密钥 #
在所选组织的设置 → API 密钥 → 组织中,选择新建组织密钥。所有套餐均可使用服务密钥。创建服务密钥需要 org:manage_api_keys。
未启用 RBAC 时,无法缩小服务密钥的权限范围:它可以使用组织内的所有本地化引擎进行读取和翻译。创建表单会显示一条说明,而不显示角色和引擎字段。
这些基本访问权限不允许密钥编辑或删除本地化引擎、审核翻译或管理组织。
启用 RBAC 后,您可以为密钥指定角色、本地化引擎范围,或同时指定两者,之后也可以修改。调用方必须有权授予所选角色,并能使用范围内的每个本地化引擎进行翻译。仅有读取权限,不足以授予相应范围的翻译权限。
允许用于服务密钥的角色为 engine:read 和 engine:translate。角色必须属于该组织,且不能包含更广泛的管理权限。服务密钥也可以不设置角色,仅依靠明确授予的资源权限。
请分别配置本地化引擎范围和内容资源范围,然后读取并核对每个已保存的字段。一项权限更新可能失败,而另一项成功。角色权限与显式授权会叠加生效;较窄的范围不会抵消角色赋予的更广泛访问权限。启用 RBAC 后,如果密钥既没有合适的角色,也未获得资源授权,仅创建密钥并不会赋予它实际可用的翻译权限。
请通过密钥管理界面创建密钥和修改范围。如果要自动化管理密钥生命周期,请确认所选客户端提供所需的管理操作,不要假设所有客户端都支持。
移除 RBAC 之前
移除 RBAC 后,普通服务密钥将恢复为拥有整个组织范围内的读取和翻译权限。已保存的角色和引擎限制将不再约束这些访问权限。如果必须保留这些限制,请在移除 RBAC 前撤销或轮换密钥。SCIM 密钥等专用凭据有各自的访问要求。
轮换或撤销凭据 #
轮换需要手动替换密钥:
- 按所需的密钥类型创建替代密钥,并仅授予必要的最小权限。
- 通过调用方的密钥管理机制保存新密钥的值。
- 更新依赖该密钥的调用方,并通过其支持的接口验证一项预期的小规模操作。
- 验证通过后,撤销旧密钥。如果密钥泄露需要立即控制风险,请先撤销,并做好应对中断的准备。
- 检查当前密钥记录和调用方的失败情况,排查遗漏的依赖。
有权访问密钥记录的组织成员可以撤销普通个人密钥或服务密钥。与创建服务密钥或修改其范围相比,撤销操作的权限要求更宽松。SCIM 密钥只能由组织所有者撤销。讨论移除密钥时,请使用密钥标识符,而不是密钥值。
撤销密钥不会清除保存在其他位置的副本,也不会撤销浏览器会话。这套生命周期流程并不意味着密钥会自动轮换或按计划到期。
配置实际调用方 #
REST 请求使用所选 API 的 X-API-Key 标头。401 表示身份验证存在问题;403 表示请求的操作未获授权。遇到前者,请核对凭据;遇到后者,请核对主体的权限和资源范围。切勿将凭据放入临时拼接的 URL 中。
有关调用方的通信和存储行为,请参阅 API 身份验证、CLI 身份验证或 MCP 连接规范。所选本地化引擎必须始终处于该调用方的权限范围内。