> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Router 的 OAuth 与 Serve 账户绑定

> 使用 POST /v1/router/auth/oauth/start 发起 OAuth 登录并通过回调完成。绑定并更新咏唱引擎 Serve 账户。

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

## 发起 OAuth 流程

发起一次 OAuth 授权请求。

### 接口

```http theme={null}
POST /v1/router/auth/oauth/start
```

### 认证

无需认证。

### 请求体

<ParamField body="provider" type="string" required>
  要使用的 OAuth 提供方名称。
</ParamField>

### 响应

<ResponseField name="authorize_url" type="string">
  用于将用户重定向以进行提供方授权的 URL。
</ResponseField>

<ResponseField name="state" type="string">
  用于 CSRF 防护的 OAuth state 参数。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://router.example.com:8080/v1/router/auth/oauth/start \
    -H "Content-Type: application/json" \
    -d '{"provider":"google"}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
    "state": "abc123xyz"
  }
  ```
</ResponseExample>

## OAuth 回调

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

### 接口

```http theme={null}
GET /v1/router/auth/oauth/callback?code=<code>&state=<state>
```

### 认证

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

### 查询参数

<ParamField query="code" type="string" required>
  OAuth 提供方返回的授权码。
</ParamField>

<ParamField query="state" type="string" required>
  OAuth 提供方返回的 state 值，用于校验请求。
</ParamField>

### 响应

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

<RequestExample>
  ```bash cURL theme={null}
  curl "https://router.example.com:8080/v1/router/auth/oauth/callback?code=AUTHCODE&state=abc123xyz" \
    -c cookies.txt
  ```
</RequestExample>

## Serve 账户

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

### 获取已绑定账户

```http theme={null}
GET /v1/router/serve/account
```

#### 认证

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

#### 响应

<ResponseField name="account_id" type="string">
  已绑定 Serve 账户的标识符。
</ResponseField>

<ResponseField name="email" type="string">
  与已绑定 Serve 账户关联的邮箱。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://router.example.com:8080/v1/router/serve/account \
    -H "Authorization: Bearer <api-key>"
  ```
</RequestExample>

### 更新已绑定账户

```http theme={null}
PUT /v1/router/serve/account
```

#### 认证

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

#### 请求体

<ParamField body="account_id" type="string" required>
  要绑定的新 Serve 账户标识符。
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"}'
  ```
</RequestExample>