§ API REFERENCE

签发免登作答入口

POST/runtime/launch-tokensscope: runtime:launch:write

为某执行签发免登 runtime 入口，把终端用户重定向到 entry_url 完成作答。

鉴权：Authorization: Bearer <access_token>。

§ 1

请求信息

REQUEST

POST https://api.lingxiguangnian.com/api/open/v1/runtime/launch-tokens

请求头

参数	类型	必填	说明
`Authorization`	string	是	Bearer <access_token>。由 POST /token 换取，有效期 2 小时；api_secret 不得直连业务端点（→ 401）。

请求体参数

参数	类型	必填	说明
`execution_id`	uuid	是	目标执行（须未终态、已冻结额度）。
`ttl_seconds`	number	否	token 有效期秒数（后端 clamp）。
`return_url`	string	否	服务提交后「返回」按钮的 HTTPS 地址；必须精确命中 APP 预登记白名单。

§ 2

调用示例

EXAMPLES

POST /runtime/launch-tokens

curl -X POST "https://api.lingxiguangnian.com/api/open/v1/runtime/launch-tokens" \
  -H "Authorization: Bearer oat_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "execution_id": "9b8e0c2a-3d4f-4a5b-8c6d-7e8f9a0b1c2d", "return_url": "https://partner.example.com/runtime/done" }'

§ 3

返回结果

RESPONSE

返回字段

参数	类型	必填	说明
`execution_id`	uuid	是	执行 ID。
`scene_solution_run_id`	uuid	是	托管执行容器 ID。
`entry_url`	string	是	免登入口 URL（#lt=明文 token，仅此一次）；把终端用户重定向到此。
`expires_at`	string	是	入口过期时间。
`return_url`	string \| null	是	本次运行冻结的回跳地址。

RESPONSE · JSON

{
  "success": true,
  "data": {
    "execution_id": "9b8e0c2a-3d4f-4a5b-8c6d-7e8f9a0b1c2d",
    "scene_solution_run_id": "5b8e0c2a-3d4f-4a5b-8c6d-7e8f9a0b1c2d",
    "entry_url": "https://partner.example.com/open-runtime/9b8e0c2a-3d4f-4a5b-8c6d-7e8f9a0b1c2d#lt=lt_xxxxxxxx",
    "expires_at": "2026-06-04T05:00:00.000Z",
    "return_url": "https://partner.example.com/runtime/done",
    "reused_run": false
  }
}

§ 4

端点错误码

ERRORS

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

HTTP	error_code	触发条件
422	`open_api.validation_error`	参数错误或资源快照已不可用。
404	`open_api.execution_not_found`	执行不存在或不属本 APP。
409	`open_api.execution_not_launchable`	执行已终态 / 缺冻结 ticket。

使用说明

entry_url 的明文 token 在 # fragment，仅返回一次；不要写入服务端日志。
return_url 必须先在机构端 APP 详情中登记；任意地址会以 422 拒绝。
启用单域名 Runtime 网关时，entry_url 与已登记 return_url 使用同一 origin；第三方只配置一个用户域名，并按接入模板代理固定 Runtime 路径。
单域名模式按已完成网关验收的 origin 显式启用；未登记的第三方即使配置了 return_url，也继续使用平台 Runtime，不会被其他 APP 的开关影响。
未启用单域名网关或网关异常回退时，entry_url 仍由平台 Runtime 提供；调用字段和执行规则不变。
全部项目提交后发送非权威导航事件 MBC_RUNTIME_SUBMITTED；点击「返回」发送 MBC_RUNTIME_RETURN_CLICKED。
Web postMessage 的 targetOrigin 从冻结 return_url 派生，不使用通配符；最终结果以状态、报告 API 或 Webhook 为准。
幂等：同一 execution 复用同一托管 run；重新签发会撤销旧 token，不重复扣费。

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