§ API REFERENCE

换取 access_token

POST/token换取 token

服务端用 api_secret 换取短期 access_token（client_credentials）。secret 仅此端点验证。

鉴权：x-app-id + Authorization: Bearer <api_secret>（secret 放请求头，禁入 URL）。

§ 1

请求信息

REQUEST

POST https://api.lingxiguangnian.com/api/open/v1/token

请求头

参数	类型	必填	说明
`x-app-id`	string	是	APP 公开标识 app_key。
`Authorization`	string	是	Bearer <api_secret>。仅 /token 验证；secret 放请求头，禁入 URL / query / 前端 / 日志。

请求体参数

参数	类型	必填	说明
`grant_type`	string	是	固定 client_credentials。

§ 2

调用示例

EXAMPLES

POST /token

curl -X POST "https://api.lingxiguangnian.com/api/open/v1/token" \
  -H "x-app-id: app_xxxxxxxx" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "client_credentials" }'

§ 3

返回结果

RESPONSE

返回字段

参数	类型	必填	说明
`access_token`	string	是	明文 token（oat_ 前缀），作后续业务调用 Bearer；仅此一次返回。
`token_type`	string	是	固定 Bearer。
`expires_in`	number	是	有效期秒数（固定 7200 = 2h）。
`scope`	string	是	授予 scope（空格分隔，= requested ∩ allowed）。

RESPONSE · JSON

{
  "success": true,
  "data": {
    "access_token": "oat_xxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 7200,
    "scope": "capabilities:read executions:write reports:read runtime:launch:write"
  }
}

§ 4

端点错误码

ERRORS

通用鉴权、scope 与限流错误见「使用概述」；下表为本端点专属错误。

HTTP	error_code	触发条件
401	`open_api.unauthorized`	app_key / secret 错或 app 非 ACTIVE（统一，不分子原因）。
422	`open_api.grant_unsupported`	grant_type 非 client_credentials。
422	`open_api.no_granted_scopes`	requested ∩ allowed 为空，无可签发 scope。
429	`open_api.rate_limited`	换发过频（防爆破）。

使用说明

secret 只展示一次，丢失只能在「密钥申请」轮换重发；轮换后旧 access_token 立即失效。
access_token 短期（2h）；服务端缓存复用，临近过期再换。

契约真源：apps/m-master/src/app/api/open/v1/token/route.ts