Docs / Authorization

Device Code Flow

SereChat uses a browser-based device-code authorization flow. Your app never handles user credentials — the user approves access in their own browser and hands you a short code to exchange for a token.

ℹNo app registration is required. Any app can start the flow by providing a human-readable app_name.

Flow overview

Create a request

Your app calls POST /api/auth/app/request with your app's display name. You receive a request_id.

User authorizes in browser

Direct the user to https://serechat.com/authorize-app?request_id={id}. They log in (if needed), see your app name, and click Authorize. A 6-digit code is shown on-screen.

User enters the code

The user copies the 6-digit code from the browser and pastes it into your app (e.g. via a CLI prompt or a text field).

Exchange code for token

Your app calls POST /api/auth/app/exchange with the request_id and the code. You receive an access_token valid for one year.

POST /api/auth/app/request

Creates a new authorization request. No authentication required.

Request body

Field	Type	Description
app_namerequired	string	Display name shown to the user on the approval screen. Max 80 characters.

Response

Field	Type	Description
request_id	string (uuid)	Unique identifier for this authorization request. Valid for 10 minutes.

json

{
  "request_id": "a1b2c3d4-e5f6-..."
}

POST /api/auth/app/exchange

Exchanges a request_id and user-entered code for a bearer token. Call this after the user approves in the browser.

Request body

Field	Type	Description
request_idrequired	string	The request ID returned by `/api/auth/app/request`.
coderequired	string	6-digit numeric code shown to the user after approval.

Response

Field	Type	Description
access_token	string	Bearer token for use in inference requests. Not stored; save it immediately.
token_type	string	Always `"bearer"`.
expires_in	number	Seconds until expiry. Currently 31 536 000 (one year).

⚠You have 5 attempts to enter the correct code before the request is invalidated and you must start over. Codes expire 5 minutes after the user approves.

Revoking tokens

Users can revoke any authorized application at any time from their Profile → Connected Applications page. Once revoked, the token immediately returns 401 on all subsequent inference calls.