Sign in with Syntic (OAuth)

Syntic’s own apps (Syntic Code, Syntic Desktop and Syntic Mobile) sign a person in through the browser instead of asking for an API key. The flow is OAuth 2.0 authorization code with PKCE: the app never sees the person’s password, and what it gets back is a short-lived access token plus a refresh token tied to one organization.

Apps are registered by Syntic. Each registered app is a public client: it has an id but no secret, so PKCE and an exactly matching redirect address are what protect the code.

The flow at a glance

1. The app makes a random code verifier, hashes it into a code challenge, and makes a random state value.
2. The app opens the browser at https://app.syntic.ai/oauth/authorize with those values.
3. The person signs in (if they are not already) and approves. The page sends the browser to the app’s redirect address with code and state added to the query.
4. The app checks that state is the value it made, then trades the code and the verifier for tokens at the token endpoint.
5. The app sends the access token as Authorization: Bearer ... on /v1 calls, refreshes it before it expires, and revokes the refresh token when the person signs out.

Registered apps

An unknown client_id is refused before anything else is checked.

Scopes are granted per app. A scope one app may hold is never available to another app just because it exists. No app can be granted a scope that creates API keys: sign-in tokens are the credential, and no long-lived key is minted for them.

Step 1: make the verifier, challenge and state

import base64, hashlib, secrets
 
def b64url(raw: bytes) -> str:
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
 
verifier = b64url(secrets.token_bytes(32))
challenge = b64url(hashlib.sha256(verifier.encode()).digest())
state = b64url(secrets.token_bytes(24))

Step 2: open the approval page

https://app.syntic.ai/oauth/authorize
  ?response_type=code
  &client_id=syntic-code-cli
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A54545%2Fcallback
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=Jb7c1Qy0pXr2uK9mZs4vTg
  &scope=user%3Ainference%20user%3Aprofile

If the person is signed out, the page sends them through the normal syntic.ai sign-in (including MFA) and then returns to the approval card. Nothing is sent to the redirect address until they approve. When a check fails (unknown app, bad redirect address, bad challenge, missing state for Mobile, unknown scope, not a member of the organization, Free plan for the CLI), the page shows the error itself and does not redirect.

On approval the browser goes to:

http://127.0.0.1:54545/callback?code=<one-time code>&state=Jb7c1Qy0pXr2uK9mZs4vTg

The code is valid for 5 minutes and can be used once.

Step 3: check the return

Before you use the code:

• Compare state with the value you made, character for character. If it is missing or different, throw the code away and show an error. Do not exchange it.
• A loopback listener should answer only GET /callback on the exact host and port it registered, and should stop listening after the first valid callback.
• Use the same redirect_uri string in step 4 that you sent in step 2.

Redirect address rules

Redirect addresses are compared exactly. There is no prefix matching, no wildcard and no normalising of what you send.

Loopback (CLI and Desktop). Run a small HTTP listener on the loopback interface, on a port the operating system picks, and register it as http://<host>:<port>/callback:

• scheme http (the listener is local, so TLS is not used; https is refused);
• host 127.0.0.1 (CLI and Desktop) or localhost (CLI only);
• an explicit port: 1 to 65535 for the CLI, 1024 to 65535 for Desktop. A missing port or port 0 is refused;
• path exactly /callback;
• no query string, no fragment, no user name or password;
• written in its plain form. The server parses your value, rebuilds http://<host>:<port>/callback, and refuses the request unless the two strings are identical, so forms such as /./callback, an encoded dot or a trailing slash fail.

Manual paste page (CLI only). When a local listener cannot be used (for example over SSH), the CLI may use https://app.syntic.ai/oauth/code/callback. That page shows the code, and the person pastes it into the terminal. The state check still applies.

Custom scheme (Mobile). ai.syntic.mobile:/oauth/callback, byte for byte. No other form is accepted for Mobile.

The value is checked twice: when the approval page asks for a code (an address outside the rules gets invalid_redirect_uri), and again at the token endpoint, where it must equal the one stored with the code (redirect_uri_mismatch).

Step 4: exchange the code

POST https://app.syntic.ai/v1/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<one-time code>",
  "code_verifier": "<verifier from step 1>",
  "client_id": "syntic-code-cli",
  "redirect_uri": "http://127.0.0.1:54545/callback"
}

The server hashes code_verifier with SHA-256, compares it with the stored challenge, and checks that client_id and redirect_uri match what the code was issued for. A malformed verifier is refused before the code is used up, so a typo does not burn a good code.

Response, 200 OK:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "q3Jx0nS1v8...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "user:inference user:profile",
  "account": { "uuid": "4c0f...", "email_address": "dev@example.com" },
  "organization": { "uuid": "a91e...", "id": "a91e..." },
  "subscription_tier": "business"
}

Step 5: refresh

Refresh shortly before expires_in runs out, or when a /v1 call answers 401 invalid_token.

{
  "grant_type": "refresh_token",
  "refresh_token": "<current refresh token>",
  "client_id": "syntic-code-cli"
}

You get back the step 4 fields, with a new refresh_token. Save the new one before you use the new access token; the old refresh token stops working at that moment.

Rotation and reuse. All refresh tokens from one sign-in form a session. Presenting a refresh token that has already been replaced is treated as theft: the whole session is revoked and the answer is 401 token_reuse_detected. The person has to sign in again. If two parts of your app might refresh at the same time, put the refresh behind a lock.

A refresh is also refused, and the session revoked, when the person is no longer an active member of the bound organization (org_membership_revoked), and for the CLI when the organization no longer has a paid plan (plan_required). When the server cannot check membership or plan, it answers 503 without using up the refresh token, so the same token works on a retry.

Step 6: sign out (revoke)

POST https://app.syntic.ai/oauth/revoke
Content-Type: application/x-www-form-urlencoded

/api/oauth/revoke on the same host is an alias. Revocation follows RFC 7009. Send the refresh token; the whole session is ended, and access tokens minted from it stop working at once.

token=<refresh token>&client_id=syntic-code-cli&token_type_hint=refresh_token

The body may also be JSON with the same three fields. token and client_id are required; token_type_hint is optional.

• The answer is 200 {"revoked": true} whether or not the token was known, already revoked, or belongs to another app (which is left untouched). This stops the endpoint from being used to test tokens.
• 401 invalid_client: client_id is missing or not registered.
• 400 invalid_request: no token, one longer than 4,096 characters, or a body that cannot be read.
• 400 unsupported_token_type: token_type_hint is access_token and the value is not a refresh token. Access tokens are ended by revoking their session.
• 503 temporarily_unavailable: try again.

Responses carry Cache-Control: no-store. Delete the stored tokens locally even if the call fails. Full reference with curl, Python and TypeScript examples: Revoke a sign-in.

Step-up: confirm it’s you

Some actions in an app (for example changing a security setting) need proof that the person signed in recently, not just that the app holds a valid session. For these the app sends the browser to:

https://app.syntic.ai/oauth/step-up?intent=<action>&client_id=...&redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256&scope=...

• intent names the action: 1 to 128 characters from A-Z a-z 0-9 _ -.
• The other parameters are the same as for /oauth/authorize, with the same rules.
• organization_id may be added to keep the session on the same organization. The organization is never switched silently.

The page asks the person to confirm their password (or sign in again with Google, SSO or MFA). The server, not the browser, decides: it issues a code only if the person’s last real sign-in was within 5 minutes (60 seconds of clock skew are tolerated). Otherwise the request is refused with 401 step_up_required, which carries reason (no_auth_time, stale_auth or future_auth_time) and max_age (300).

The app then finishes with the normal state check and code exchange. The first access token from that code carries the step-up (the action and the sign-in time); a protected action accepts it for up to 10 minutes after the sign-in. Refreshed access tokens never carry a step-up, so a step-up cannot be stretched by refreshing.

Error codes

Approval page

These are shown on the page; nothing is redirected to the app.

Token endpoint

Checklist for app builders

• New verifier, challenge and state for every sign-in; never reused.
• code_challenge_method=S256 sent every time.
• state compared on return; a mismatch ends the sign-in.
• One redirect_uri string, built once, used for the approval page, the listener and the token request.
• Listener bound to the loopback address only, closed after the first valid callback.
• Refresh tokens kept in the system’s secure store and replaced after every refresh.
• One refresh at a time.
• Sign-out calls revoke, then deletes local tokens even if revoke fails.

Related

• Revoke a sign-in
• Authentication
• Error codes
• Exchange a workload token