身份验证

API 版本 2026-10-affable-towhee

每次调用 Lingara API 都要携带一个访问令牌。服务器在令牌端点用 OAuth 客户端的 ID 和密钥换取访问令牌：这就是 OAuth 2.0 的客户端凭据授权，适用于以自身身份运行的服务器。请在 Lingara 网页应用的集成页面创建客户端，地址为 app.getlingara.com/admin。

会话还是客户端

Lingara 应用通过会话让你登录，会话拥有所有权限范围，并消耗你套餐的额度。客户端的权限更窄：创建时由你选择它被允许的权限范围，而它获得的每个访问令牌只带有它所申请的权限范围。

三个值

客户端 ID 以 lgr_cid_ 开头，用于在令牌端点标识该客户端。它不是机密。

客户端密钥以 lgr_cs_ 开头，只发送到令牌端点。它仅在创建时显示一次：请当场复制，因为 Lingara 只存储它的哈希值。

访问令牌以 lgr_at_ 开头，有效期为一小时。它放在 /v1/ 下各调用的 Authorization: Bearer 标头中，不用于其他任何地方。该标头中只能放访问令牌：在那里发送客户端密钥会被拒绝，返回 401。

获取访问令牌

用 POST 向令牌端点提交一个表单，其中包含 grant_type=client_credentials。客户端 ID 和密钥可以通过 HTTP Basic 身份验证发送，也可以作为 client_id 和 client_secret 表单字段发送，但不能两者同时使用。scope 是以空格分隔的权限范围列表，只能包含该客户端被允许的权限范围；省略它则获得该客户端被允许的全部权限范围。下面的命令只申请 usage:read，即后文 GET /v1/usage 示例所需的权限范围。

curl -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read"

响应包含 access_token、token_type（Bearer）、expires_in（3600，单位为秒）和 scope，即该令牌实际拥有的权限范围。换取失败时，以 OAuth 错误格式 {error, error_description} 应答，而不是 /v1/ 的 {code, error} 信封。密钥错误或已撤销，或客户端已删除，会被拒绝并返回 401 和 invalid_client。申请客户端无权申请的权限范围会使整个换取被拒绝，返回 400 和 invalid_scope；权限范围绝不会被悄悄缩小。

代表其他 Lingara 用户操作

代表其他 Lingara 用户操作的应用使用授权码授权。将用户的浏览器引导到授权 URL，并附带 response_type=code、client_id、与你注册的某个地址完全一致的 redirect_uri、scope、state 以及采用 S256 的 code_challenge。用户会看到 Lingara 的授权同意页面，随后带着 code、state 和 iss 返回你的 redirect_uri。使用该授权码之前，请确认 state 正是你发送的值，并且 iss 为 https://api.getlingara.com。

必须使用 PKCE

每个客户端都使用 PKCE，且只支持 S256 方法。生成一个随机的 code_verifier，将其 SHA-256 哈希值经 base64url 编码后作为 code_challenge 发送，同时带上 code_challenge_method=S256，并保留该验证码以供换取时使用。未指定方法或使用 plain 的请求会被拒绝，返回 invalid_request。

换取授权码

在 60 秒内，用 POST 向令牌端点提交 grant_type=authorization_code、code、相同的 redirect_uri 和 code_verifier，并以客户端身份进行身份验证；公共客户端只发送 client_id。响应中会额外包含一个以 lgr_rt_ 开头的 refresh_token。授权码以 lgr_ac_ 开头，只能使用一次：第二次使用会被拒绝并返回 invalid_grant，同时使第一次换取所签发的令牌全部失效。

刷新

访问令牌过期时，用 POST 向令牌端点提交 grant_type=refresh_token 和 refresh_token，并再次以客户端身份进行身份验证。每次刷新都会返回一个新的刷新令牌：只保留最新的那个。请依次进行刷新，不要并发：旧的刷新令牌在被替换超过 60 秒后仍被使用，会被视为已被盗用，该安装的所有令牌都会失效，并返回 invalid_grant。连续 30 天未使用的刷新令牌会过期。令牌端点会按地址限制请求次数，因此只在令牌用完时才刷新。

原生应用是公共客户端

桌面、移动或命令行应用无法保管密钥，因此属于公共客户端：它没有密钥，只向令牌端点发送 client_id，并注册一个回环重定向地址，例如 http://127.0.0.1/callback（任意端口），或一个私有 URI 方案，例如 com.example.app:/callback。用户每次都会看到授权同意页面。网页不能作为客户端：令牌端点和 /v1/ 都不响应跨域预检请求。

当用户移除你的应用时

用户可以随时在“已连接的应用”中移除你的应用；如果是用户自己安装的，也可以直接卸载，此后该应用的下一次调用会以 401 失败。当用户退出你的应用时，请在撤销端点撤销其刷新令牌，这会使该安装的所有令牌失效。

令牌过期时

一小时后，/v1/ 会返回 401，代码为 unauthorized，错误以 invalid_token 开头。当调用收到 401 时，或在 expires_in 即将用完之前，重新换取，并将该调用重试一次。如果换取本身以 invalid_client 或 invalid_scope 失败，说明客户端或其密钥已被删除、撤销或缩小了权限范围：请停止，并到集成页面修正，因为重试不可能成功。请在多次调用之间保留令牌：令牌端点会按客户端和地址限制换取次数，每次调用都换取的程序会在一小时内被拒绝，返回 429 和 rate_limited（请等待 Retry-After）。此授权没有刷新令牌：需要再次用密钥换取。

访问令牌只能访问 API 路由

访问令牌只在 /v1/ 下的路由有效。发送到 Lingara 的其他任何路由时，会被拒绝并返回 401，响应体以 api_token_not_accepted 开头，可能是纯文本，也可能位于 error 字段中，绝不会采用 /v1/ 路由所用的 {code, error} 信封。请如下所示，在 Authorization 标头中发送访问令牌。

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

权限范围

每个操作恰好需要一个权限范围，其名称写在该操作的页面上。缺少该权限范围的访问令牌会被拒绝，返回 403 和代码 insufficient_scope。要调用该操作，请在换取时申请它的权限范围（前提是客户端被允许使用该权限范围）。下表列出了每个权限范围及其允许的操作。

由谁为调用付费

客户端有两种计费方式，在创建时选定。allowance 客户端消耗其所有者的额度，与你的应用是同一份额度，它的访问令牌也消耗这份额度；GET /v1/usage 会显示剩余多少。metered 客户端不消耗额度：它通过你在集成页面设置的按用量计费订阅，按点数计费。一旦客户端或你的账户达到每月支出上限，它的调用会以 402 和 spend_cap_reached 被拒绝；按用量计费未激活时，则以 402 和 metered_billing_inactive 被拒绝。一份课程计划计 10 点，一轮辅导对话计 1 点，一次词汇生成计 3 点，因此 GET /v1/usage 报告的 units 可按这些权重换算为点数。应用代表其他用户、使用通过授权码获得的令牌发起的调用，无论客户端采用哪种模式，始终消耗该用户的额度。

将密钥和令牌保存在服务器上

客户端密钥应存放在你控制的服务器上，绝不能放在网页、浏览器扩展或应用安装包中，因为任何人都能在那里读取它。原生应用是公共客户端，不持有密钥。/v1/ 和令牌端点都不响应跨域预检请求，因此其他网站上的浏览器本来也无法调用它们。

管理客户端

在集成页面（地址为 app.getlingara.com/admin）上，你可以创建、重命名和删除客户端，更改每个客户端能做什么以及固定到哪个版本，并创建和撤销它的密钥。删除客户端会立即使它持有的所有访问令牌失效，并终止所有用户对它的授权。撤销密钥会立即使用该密钥换取的所有访问令牌失效。缩小客户端的权限范围同样立即生效；扩大权限范围或更改版本，则从下一次换取起生效。

轮换密钥

一个客户端可以同时持有两个密钥。要轮换密钥，请创建新密钥并部署它，等集成页面上旧密钥的“上次使用”日期不再变化后，再撤销旧密钥。已拿到新密钥、但仍持有旧密钥换来的令牌的进程，会收到一次 401，然后重新换取。客户端唯一的密钥无法撤销：请先创建替代的密钥，或者删除该客户端。

如译文与英文参考文档不一致，以英文参考文档为准。