API 密钥
API 密钥用于验证发往本地化 API 和 MCP server 的请求。Lingo.dev 提供两种类型——请选择与你的 API 调用方相匹配的那一种。
两种类型的密钥#
| 个人 | 组织 | |
|---|---|---|
| 归属者 | 创建它的用户 | 无——面向自动化场景 |
| 授权方式 | 继承创建者的 RBAC role 和引擎授权 | 拥有自己的角色和/或按引擎划分的作用域 |
| 如果归属者失去访问权限 | 该密钥也会同时失去访问权限 | 不受影响；由密钥自身的角色/作用域控制 |
| 套餐 | 所有套餐均可用 | 企业版（需要 RBAC entitlement） |
| 典型用途 | 本地开发、MCP、临时脚本 | CI/CD 流水线、生产环境集成 |
个人密钥是默认选项。组织密钥属于组织级资源，不依附于任何单一员工，因此特别适合需要在员工离职后继续使用、且不受角色变更影响的凭据。
创建密钥#
打开 设置 中的 API keys 页面。个人密钥和组织密钥分别位于不同标签页；组织 标签页需使用 Enterprise 方案。
点击 New personal key，为密钥命名（例如“Local MCP”或“Max 的预发布密钥”），并在显示后立即复制。该密钥会继承你当前的 RBAC 角色以及按引擎授予的权限。
密钥可见性
完整的 API 密钥只会在创建时显示一次。请务必复制并妥善保存——关闭弹窗后将无法再次查看。
组织密钥与 RBAC#
组织密钥沿用与用户相同的模型：用户可以拥有组织级角色（通过 Roles & Permissions 获得整体权限），以及/或者被授予特定引擎的访问权限。组织密钥也是同样的机制：
- 仅角色 —— 该角色的权限会在整个组织范围内生效。如果其中包含
engine:access，该密钥就可以访问组织中的所有引擎。 - 无角色 + 引擎范围 —— 密钥仅可访问你在创建时勾选的引擎。之后可通过编辑该密钥更新引擎列表。
- 角色 + 引擎作用域 —— 两种授权来源会叠加生效。如果角色授予了
engine:access，则以角色的全局权限为准；否则会参考按引擎配置的列表。 - 两者皆无 —— 该密钥可以完成身份验证，但无法访问任何引擎。可在你尚未配置作用域时作为占位使用，但在生产环境中并无实际意义。
防止权限升级的保护机制会在创建和编辑时生效：
- 所选角色必须属于同一组织。
- 该角色的权限集必须是
engine:access的子集——权限更宽的角色（例如包含org:manage_team的角色）会被拒绝。 - 只有当你自己已经有权限访问某个引擎时，才能把它加入该密钥的作用域。
如果企业版套餐失效
组织密钥受 RBAC 权益控制。如果这项权益被移除，所有组织密钥都会被停用——请求会返回 403，并显示一条指向方案的消息，而不是指向引擎范围。个人密钥不受影响。你可以恢复 Enterprise 方案，或改用个人 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，它就会被拒绝——请在它变成孤立密钥之前完成轮换。
- 组织密钥拥有独立的权限控制。编辑角色或范围会立即生效；删除密钥则会立即撤销其权限。
- 每个组织可创建的密钥数量没有限制。