Router 的 OAuth 与 Serve 账户绑定

咏唱引擎 ROUTER 支持基于 OAuth 的认证，以及绑定到咏唱引擎 Serve 账户。使用 OAuth 发起接口将用户重定向到身份提供方，然后处理回调以建立会话。已绑定的 Serve 账户信息可通过专用的管理接口查看与更新。

发起 OAuth 流程

发起一次 OAuth 授权请求。

接口

POST /v1/router/auth/oauth/start

认证

无需认证。

请求体

string

required

要使用的 OAuth 提供方名称。

响应

string

用于将用户重定向以进行提供方授权的 URL。

string

用于 CSRF 防护的 OAuth state 参数。

curl -X POST https://router.example.com:8080/v1/router/auth/oauth/start \
  -H "Content-Type: application/json" \
  -d '{"provider":"google"}'

{
  "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
  "state": "abc123xyz"
}

OAuth 回调

在用户于提供方处授权后完成 OAuth 流程。

接口

GET /v1/router/auth/oauth/callback?code=<code>&state=<state>

认证

无需认证。回调会用授权码换取会话并设置会话 Cookie。

查询参数

string

required

OAuth 提供方返回的授权码。

string

required

OAuth 提供方返回的 state 值，用于校验请求。

响应

回调成功会设置会话 Cookie 并返回用户摘要字段。

curl "https://router.example.com:8080/v1/router/auth/oauth/callback?code=AUTHCODE&state=abc123xyz" \
  -c cookies.txt

Serve 账户

查看或更新与当前 Router 用户绑定的咏唱引擎 Serve 账户。

获取已绑定账户

GET /v1/router/serve/account

认证

发送会话 Cookie 或 Authorization: Bearer <api-key>。

响应

string

已绑定 Serve 账户的标识符。

string

与已绑定 Serve 账户关联的邮箱。

curl https://router.example.com:8080/v1/router/serve/account \
  -H "Authorization: Bearer <api-key>"

更新已绑定账户

PUT /v1/router/serve/account

认证

发送会话 Cookie 或 Authorization: Bearer <api-key>。

请求体

string

required

要绑定的新 Serve 账户标识符。

curl -X PUT https://router.example.com:8080/v1/router/serve/account \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api-key>" \
  -d '{"account_id":"serve-acc-456"}'

PIN API

ROUTER API

AGENT API

Router 的 OAuth 与 Serve 账户绑定

发起 OAuth 流程

接口

认证

请求体

响应

OAuth 回调

接口

认证

查询参数

响应

Serve 账户

获取已绑定账户

认证

响应

更新已绑定账户

认证

请求体

​发起 OAuth 流程

​接口

​认证

​请求体

​响应

​OAuth 回调

​接口

​认证

​查询参数

​响应

​Serve 账户

​获取已绑定账户

​认证

​响应

​更新已绑定账户

​认证

​请求体

发起 OAuth 流程

接口

认证

请求体

响应

OAuth 回调

接口

认证

查询参数

响应

Serve 账户

获取已绑定账户

认证

响应

更新已绑定账户

认证

请求体