How browser-approval device login works

When you sign SynapseX Desktop or the SynapseX CLI into your account, they do not ask for your password. They show you a short code and send you to a browser. This page explains what that flow does, so you can tell a normal wait from a real failure, and so you know exactly what your machine ends up holding. At the end you will have run the first step yourself and seen the real response.

Why not just paste a key?

A terminal or a desktop app is a bad place for a long-lived secret. If a credential is typed into a shell it lands in your shell history; if it is pasted into a chat window or a ticket to “get unblocked”, it is exposed for as long as it exists. And an app that asks for your account password is asking for a credential far more powerful than the one it needs.

Browser approval solves both. Your password is only ever entered on chat.synapsex.ai, in a browser where you may already be signed in. The device never sees it. What the device gets instead is its own narrow, revocable credential.

What are the four steps?

The client requests a code. SynapseX Desktop or the CLI calls POST https://chat.synapsex.ai/api/auth/device/code. It gets back a private device_code (which it keeps) and a short user_code (which it shows you).
You open the approval page. The client opens https://chat.synapsex.ai/activate in your browser — usually with the code already in the URL. If you are not signed in, sign in there first.
You confirm the code. Check that the code on the page matches the code your app is showing, and approve. This step is what ties the device to your account.
The client receives its own credential. While you were approving, the client was polling POST https://chat.synapsex.ai/api/auth/device/token. Once you approve, that poll returns the credential — once, and only once.

What are the numbers you can observe?

Thing	Value	Why it matters
Code lifetime	900 seconds (15 minutes)	Walk away for too long and you start over
Poll interval	5 seconds	The client is told how often it may ask; polling faster is rejected
Code shape	`XXXX-XXXX`, 8 characters	Short enough to read aloud or retype
Code alphabet	Excludes look-alike characters	There is no `0`, `O`, `1` or `I` in a code, so you never have to guess

Try step one yourself

This call is unauthenticated by design — the approval, not the request, is what proves who you are. Run it:


curl -s -X POST https://chat.synapsex.ai/api/auth/device/code \
  -H "Content-Type: application/json" \
  -d '{"client_id":"synapsex-code"}'

Real response (HTTP 201), with the private device_code replaced by a placeholder:


{
  "device_code": "YOUR-DEVICE-CODE",
  "user_code": "CMSR-QYAT",
  "verification_uri": "https://chat.synapsex.ai/activate",
  "verification_uri_complete": "https://chat.synapsex.ai/activate?code=CMSR-QYAT",
  "expires_in": 900,
  "interval": 5
}

That is the whole handshake in one object: the code you type (user_code), the page you type it on (verification_uri), a shortcut link that pre-fills it (verification_uri_complete), how long you have (expires_in) and how often the client may poll (interval).

Open verification_uri_complete in a signed-in browser and you will see the approval page for that code. If you do not complete it, nothing happens — an unapproved code simply expires.

What do the polling errors mean?

While you are approving, the client polls the token endpoint. Each of these comes back as HTTP 400 with a single error field:

Response	Meaning	What to do
`{"error":"authorization_pending"}`	Normal. Nobody has approved the code yet	Nothing — finish approving in the browser
`{"error":"slow_down"}`	The client polled faster than the 5-second interval	Nothing — the client backs off on its own
`{"error":"access_denied"}`	The approval was refused in the browser	Start the sign-in again
`{"error":"expired_token"}`	The 15 minutes ran out, or this code was already claimed	Start the sign-in again to get a fresh code

Only the last two are real failures. authorization_pending is what a healthy flow looks like for as long as you are still clicking.

What does the device end up holding?

On approval the client receives a personal API key in the sxc_ format, carrying the compute scope, and stores it locally. Three properties follow from that, and they are the practical payoff of this whole design:

It is per device. Your laptop and your work machine each hold a different key.
It is revocable independently. Revoking one machine does not sign the others out.
It is not your password. It cannot be used to sign in to the website or change your account.

You revoke a device from the browser: chat.synapsex.ai → Settings → API Keys, where every active key is listed with its name and its short prefix. Full details are on Chat API keys.

For SynapseX Desktop, one approval is enough to provision both of the credentials the app keeps — its model credential and its compute credential — so you approve once rather than twice.

Scope of this page

This flow is documented for chat.synapsex.ai, which is where SynapseX Desktop and the SynapseX CLI sign in. Keys for the Platform API are a separate thing entirely: you create them in the workspace console at platform.synapsex.ai. See API keys and Which SynapseX key do you need?.

Sign in to SynapseX Desktop — the same flow, with the exact click path.
CLI authentication — the same flow from a terminal.
How SynapseX fits together — why there are two hosts in the first place.