<span id="浏览器退出与回调协议"></span>

# Browser logout and callback protocol

Ending product and UC sessions involves local revocation, obtaining an upstream navigation URL, browser navigation, and a callback. Each phase has a distinct success scope. HTTP 200 or page navigation alone does not establish complete logout.

<span id="发起产品退出"></span>

## Start product logout

`POST /auth/logout` requires a valid product session and a CSRF Cookie matching the stored hash. The current bare logout handler reads CSRF from the Cookie. Ordinary product write APIs protected by requireIdentity instead read one X-CSRF-Token header; do not conflate these paths. Normal frontend SSO writes also include that header.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

The JSON example shows only the target and account UI language. Cookies come from the browser session flow:

```json
{"return_to":"/workspace/example?tab=run#log","locale":"en-US"}
```

:::::
:::::{tab-item} Parameters

| Parameter | Location | Description |
| --- | --- | --- |
| return_to | body | Optional safe relative path. Omission uses /; an explicit empty string is rejected. Safety rules match login targets. |
| locale | body | Optional account UI language; after trimming, must be one of six supported values. Explicit empty strings are rejected. |

At most 4096 bytes; unknown fields and a second JSON object are rejected. Empty bodies and JSON null become zero-value requests. The same file's reward API 1 MiB limit does not apply. No business workspace parameter exists.

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{"code":"OK","data":{"logout_url":"https://uc.example.test/example-end-session"}}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| code | string | OK; current success envelope has no msg. |
| data.logout_url | string | UC logout URL for the browser's next navigation. May contain sensitive values such as id_token_hint; do not record the complete URL in public logs. |

Local session revocation is committed before 200, but UC logout is not yet established. The browser must navigate to the returned URL and finish the callback. URL construction/discovery may fail after local revocation. An error does not mean nothing executed. Recover according to actual session state and errors, without automatically replaying old state.

:::::
::::::
:::::::

Errors may be 400 ErrParamInvalid, 401 unauthenticated, 403 ErrForbidden, 502 ErrServiceUnavailable, or 500 ErrServer. msg is HTTP status text. On request failure, the frontend retains local state and stops navigation; this does not guarantee the backend session remains valid.

<span id="完成退出回调"></span>

## Complete the logout callback

`GET /auth/logout/callback?state=<服务端签发状态>`. state comes from upstream logout handoff, not caller-generated data.

The service consumes an unexpired, unused logout state and creates new login state in one transaction. The handler clears session/CSRF Cookies, sets a new login binding, and redirects 302 to login navigation. It is not a static logged-out page and does not mean a new login has completed automatically.

<span id="get退出入口"></span>

## GET logout entry point

`GET /auth/logout` currently returns 405 directly, without a logout URL or session clearing. This is an explicit rejection branch, not an additional ordinary GET logout capability. Older links in other deployments do not establish support in this source.
