API 身份验证

验证 API 请求的身份,并授予各项操作所需的访问权限。

通过 X-API-Key 标头发送 Lingo.dev API 密钥。本节 API 参考文档使用 https://api.lingo.dev/v2 作为基础 URL。

http
GET /v2/organizations/YOUR_ORGANIZATION_ID/localization/jobs HTTP/1.1
Host: api.lingo.dev
X-API-Key: YOUR_API_KEY

通过 API 密钥创建密钥,并将其存储在服务器环境或机密管理器中。切勿将密钥放入代码仓库、浏览器打包文件、URL 或源文档。

选择凭据 #

个人密钥以所属用户当前的成员身份和权限执行操作。组织服务密钥归组织所有,适合无人值守的服务使用。其访问权限由角色授权和资源授权共同决定;范围更窄的显式授权不会缩减角色已授予的访问权限。

API 也接受已登录用户的会话访问令牌作为 Authorization: Bearer <access-token>。审核者可以通过自己的用户会话或个人密钥提交审核决定。服务密钥不能用于作出人工审核决定,因为这类操作必须明确具体的人员身份。

每个请求只使用一种身份验证方式。标头名称不区分大小写。

选择组织和引擎 #

组织级路由的路径中包含 orgId。要查找用户或个人密钥对应的组织 ID,请读取 GET /v2/users/me/memberships。使用服务密钥时,请选择该密钥所属的组织。引擎 ID 用于标识在 Studio 中配置的引擎;使用 GET /v2/organizations/:orgId/engines 可列出有权访问的引擎。

创建、启动、读取和下载本地化任务,都需要拥有任务所属组织的访问权限,以及对应引擎的翻译权限。资源配置需要编辑或创建引擎的权限,以及创建所请求指导内容的权限。审核翻译时,遵循审核者的权限和路由规则。

传入组织或引擎 ID 并不会授予访问权限。资源不在调用方的访问范围内时,可能返回 404。因此,找不到已知资源时,请同时核对 ID 和调用方的权限。

诊断访问失败 #

请同时查看问题响应及其 HTTP 状态码。401 表示凭据缺失、无效或已过期。402 表示存在计费或套餐相关问题,包括服务密钥因 RBAC 降级而被停用的情况。403 表示权限被拒绝,或操作要求提供用户身份。引擎配置和账户限制问题则需要分别处理。

保留问题的 type、状态码及不涉密的资源 ID,以便诊断。切勿在日志中记录身份验证标头。

轮换密钥 #

创建新密钥,授予所需的访问权限,并更新服务中存储的密钥。撤销旧密钥前,请确认新密钥能够获取现有任务并下载结果。保留已记录的任务 ID:轮换凭据不会改变任务的标识。