Refresh Token

POST /auth/refresh

A reused token revokes the whole family and returns the same 401 as an unknown one.

The body became optional so a browser can send nothing at all and let the cookie speak. refresh_token is still required inside the body, so a machine client that opens one still has to fill it in and min_length=16 still applies; what widened in the generated SDKs is only the body argument, from required to optional, which no existing call stops typechecking against.

A refusal erases the cookie, but only if one was presented. The family is gone — by expiry, by logout or by the replay detector — and a browser that keeps re-offering a dead credential turns every page load into a pointless round trip. Machine callers get no Set-Cookie on the way out because they sent none on the way in.

No credential

This operation is public: it authenticates by its own mechanism — a webhook signature or a channel token — rather than by a platform credential.

Parameters

Name	In	Type		Notes
__Host-agentplat_refresh	cookie	string | null	optional	The refresh credential, as the HttpOnly cookie this endpoint and /auth/login set. Browsers send it automatically; cross-origin callers need credentials: 'include'. Ignored when the body carries a token.

Responses

Status	Description	Body
200	Successful Response	TokenPair
422	Validation Error	HTTPValidationError

Only the success paths are declared

Any operation may also answer any status in the error catalogue, and every failure body is the platform envelope — including the 422 this document types as HTTPValidationError.

Example

The body shows the fields the schema always carries. Which combination is legal is a service rule the schema cannot express, so read the description above before copying this.

curl -X POST https://your-deployment.example.com/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
       "refresh_token": "string"
     }'

Response — TokenPair

Field	Type		Notes
access_token	string	required	—
refresh_token	string	required	—
token_type	string	optional	Default "bearer".
expires_in	integer	required	—
principal	PrincipalView	required	—