<span id="浏览器登录与回调协议"></span>

# Browser login and callback protocol

Browser product login begins at the login endpoint, then UC returns to the product callback. Both use navigation, Cookies, and one-time server state rather than a regular PAT JSON sequence.

<span id="开始登录"></span>

## Start login

`GET /auth/login`. The deployment determines the actual product prefix.

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

Browser navigation example; return_to is the in-product path after login:

```text
GET $PRODUCT_ENDPOINT/auth/login?return_to=%2Fworkspace%2Fexample&lang=zh-CN
```

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

| Parameter | Location | Description |
| --- | --- | --- |
| return_to | query | Optional in-product relative path, mutually exclusive with product_continuation. If both are omitted, the service uses / |
| product_continuation | query | Optional server-issued one-time handoff value, mutually exclusive with return_to. Callers cannot forge it |
| lang | query | Optional account-login UI language: zh-CN, en-US, fr-FR, es-ES, ar, id-ID; case-sensitive |

Explicitly empty return_to/product_continuation, repeated target parameters, or both targets cause failure navigation. Repeated/unsupported lang directly returns 400/ErrParamInvalid. Relative targets are limited to 2048 bytes, start with one / rather than //, contain no backslash, and parse without Host/User/absolute-URI/opaque components. These rules do not replace complete production-domain/callback configuration validation.

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

Success returns 302, Location, and the login-binding Cookie. Continue the full flow at the UC authorization page;302 does not mean login completed. Browsers/callers must retain Cookies under the correct origin/path. See [Cookies and environments](cookies-environments.md).

The server creates state, nonce, PKCE verifier, and binding values. The UC authorization URL uses an S256 challenge and product continuation. Existing continuation consumption and subsequent login-state creation share one system transaction. After failure, callers must not reuse old handoff values themselves. With continuation, UI language comes from its issuing state; lang does not override it. TTL is deployment-configured, not inferred from test values.

<span id="完成登录回调"></span>

## Complete the login callback

`GET /auth/callback`. UC navigates to this address; business callers must not construct token-exchange requests themselves.

| Parameter | Location | Current consumption |
| --- | --- | --- |
| state | query | Server-issued state. The handler uses the first value, which must match the binding Cookie and an unconsumed record |
| code | query | Authorization code. Exactly one of code and error must be nonempty |
| error | query | Upstream failure identifier, mutually exclusive with nonempty code |

Per-state binding Cookies take precedence. The old fixed binding Cookie is read only if the per-state Cookie is absent. Repeated Cookies, missing binding, or invalid state cause failure navigation. If state contains a UI-language suffix, the full value enters the stored hash; the Cookie-name token excludes the suffix.

The callback consumes state/associated continuation, exchanges and validates tokens, checks nonce and active UC session/subject, then persists product identity/session. One-time state consumption commits before UC exchange. The entire callback is not one atomic transaction spanning UC/local storage. Do not automatically replay the original callback after downstream failure.

Success sets product session and CSRF Cookies, clears this login-binding Cookie, and redirects302 to the original safe target. Inactive UC sessions or missing handles may restart login once and clear old session Cookies; another failure opens the failure page. Arbitrary302 does not prove a product session exists. [Read the current session](browser-session.md) afterward.

Persistence retries only MySQL numeric code 20702, at most three attempts100 milliseconds apart using new transactions, stopping promptly on cancellation. This does not authorize browser replay. Provider/state/persistence errors generally cause failure navigation; failure constructing that navigation may return 500.
