API 密钥用于验证发往本地化 API 和 MCP server 的请求。Lingo.dev 提供两种类型——请选择与你的 API 调用方相匹配的那一种。
两种类型的密钥#
| 个人 | 服务 | |
|---|---|---|
| 归属者 | 创建它的用户 | 无——面向自动化场景 |
| 授权方式 | 继承创建者的 RBAC role 和引擎授权 | 拥有自己的角色和/或按引擎划分的作用域 |
| 如果归属者失去访问权限 | 该密钥也会同时失去访问权限 | 不受影响；由密钥自身的角色/作用域控制 |
| 套餐 | 所有套餐均可用 | 企业版（需要 RBAC entitlement） |
| 典型用途 | 本地开发、MCP、临时脚本 | CI/CD 流水线、生产环境集成 |
个人密钥是默认选项。服务密钥属于组织级资产，不依附于任何单个员工，因此更适合那些需要在员工离职后继续有效、并能经受角色变更的凭据。
创建密钥#
在控制台中打开 API Keys 页面。Personal 和 Service 分别位于不同的标签页——只有当你的组织使用企业版套餐时，才会显示 Service 标签页。
点击 Create API key，为密钥命名（例如“Local MCP”“Max 的预发布密钥”），然后在成功弹窗中复制密钥。该密钥会继承你当前的 RBAC 角色以及按引擎授予的权限。
密钥可见性
完整的 API 密钥只会在创建时显示一次。请务必复制并妥善保存——关闭弹窗后将无法再次查看。
服务密钥与 RBAC#
服务密钥遵循与用户相同的模型：用户可以拥有组织级角色（通过 Roles & Permissions 获得覆盖全局的权限），也可以通过被添加到特定引擎而获得按引擎授予的权限，二者还可以同时存在。服务密钥也是同样的机制：
- 仅角色 —— 该角色的权限会在整个组织范围内生效。如果其中包含
engine:access，该密钥就可以访问组织中的所有引擎。 - 无角色 + 引擎作用域 —— 该密钥只限访问你在创建时勾选的引擎。后续可通过密钥旁的 Engines x/y 按钮更新列表。
- 角色 + 引擎作用域 —— 两种授权来源会叠加生效。如果角色授予了
engine:access，则以角色的全局权限为准；否则会参考按引擎配置的列表。 - 两者皆无 —— 该密钥可以完成身份验证，但无法访问任何引擎。可在你尚未配置作用域时作为占位使用，但在生产环境中并无实际意义。
防止权限升级的保护机制会在创建和编辑时生效：
- 所选角色必须属于同一组织。
- 该角色的权限集必须是
engine:access的子集——权限更宽的角色（例如包含org:manage_team的角色）会被拒绝。 - 只有当你自己已经有权限访问某个引擎时，才能把它加入该密钥的作用域。
如果企业版套餐失效
服务密钥属于 RBAC entitlement 的一部分。如果该授权被移除，组织中的所有服务密钥都会被停用——请求会返回 403，并提示问题出在套餐，而不是引擎作用域。个人密钥不受影响。你可以恢复企业版套餐，或改用个人 API 密钥并完成轮换。
使用密钥#
在每次请求中，通过 X-API-Key 请求头传递 API 密钥——两种类型的传输格式完全一致：
bash
curl -X POST https://api.lingo.dev/process/localize \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"engineId": "eng_abc123", "sourceLocale": "en", "targetLocale": "de", "data": {"greeting": "Hello"}}'同一把密钥既可用于 localization API，也可用于 MCP server。
安全#
- 密钥以哈希形式存储——Lingo.dev 无法在创建后找回密钥。如需轮换，请删除后重新创建。
- 个人密钥会实时跟随创建者的权限变化。如果创建者的角色被降级，或某项引擎授权被撤销，该密钥会在下一次调用时失去相同的访问权限。
- 如果个人密钥的创建者已被移出组织，该密钥只会在 RBAC 关闭时继续生效（旧行为）。一旦启用 RBAC，它就会被拒绝——请在它变成孤立密钥之前完成轮换。
- 服务密钥拥有独立的授权。通过 Service 标签页编辑角色或作用域会立即生效；删除该密钥则会立刻撤销其权限。
- 每个组织可创建的密钥数量没有限制。
