Choose an integration path

Sudomimus offers four peer integration paths. Choose the one that matches your client and existing stack; none is a prerequisite for another.

Path	Best fit	Protocol shape	Start here
Connect	Web applications and custom browser sign-in	establish → authenticate → redeem → refresh	Connect flow
OIDC	Frameworks and partner systems that already speak OpenID Connect	Authorization code + PKCE	OIDC flow
Device authorization	CLIs, launchers, terminal tools, and public clients without a client secret	device-authorize → browser approval → device-token	Device authorization flow
Native direct-issue	Games, desktop apps, CLIs, and services with Steam tickets or AccessKeys	One credential exchange, with an optional browser errand for remediation	Native flows

Using the official Sudomimus CLI?

The table above is for applications you are building. If you want an AI assistant or local script to operate Sudomimus itself, use the Sudomimus CLI instead.

Browser polling is Connect, not direct-issue

A desktop application can also open the system browser and use Connect with STATUS_POLL. That flow belongs to the Connect protocol even though the client is native. The Native section documents it alongside direct-issue so desktop integrators can compare both choices.

Device authorization is not Connect STATUS_POLL

Both flows can involve a native-looking client and a browser, but their trust model is different. Connect STATUS_POLL starts from a signed /establish request by a confidential client; device authorization starts from an unsigned public-client /device-authorize request and requires a Layer 3 DEVICE_CODE ReturnRule.

The four paths are exposed through five public services. The shared browser service is via.sudomimus.com, the hosted UI used by Connect, OIDC, device approval, and native errands.

The five surfaces

Domain	Audience	Protocol
connect-api.sudomimus.com	Application backend	Connect protocol (JSON over HTTPS)
via.sudomimus.com	End users in a browser	Hosted auth page (browser-only)
device-api.sudomimus.com	Public clients (CLIs, launchers, shared devices)	Device authorization (JSON over HTTPS)
native-api.sudomimus.com	Native clients (desktop apps, games, CLIs)	One-shot direct-issue (JSON over HTTPS)
oidc.sudomimus.com	OIDC relying parties	OpenID Connect 1.0

connect-api.sudomimus.com

The HTTPS API your application backend calls. It hosts:

• Inquiry lifecycle: POST /establish, POST /redeem, POST /status-poll, POST /info
• Token operations: POST /refresh, POST /introspect, POST /logout, POST /revoke-all

/establish and /revoke-all require a client-auth JWT signed with the application’s client-auth private key (RS256, 60-second lifetime, body-bound via body_sha256, replay-protected via jti). The other endpoints are either self-authenticating (the token itself proves the right to act on its own session) or public (/info).

See Connect flow for end-to-end examples and Managing sessions for the token-operation endpoints.

via.sudomimus.com

A hosted web page that runs the actual user-facing authentication flow — passkey prompts, email OTP entry, platform sign-ins. Your application redirects the user to via.sudomimus.com with an exposure-key; the user completes the challenge there; control returns to your application according to the inquiry’s return method.

via.sudomimus.com is the user-facing surface. Your code never calls its endpoints directly — it just sends users there.

device-api.sudomimus.com

For public clients that cannot safely hold an application client-auth private key. It hosts:

• POST /device-authorize — start a short-lived device-code session and receive { deviceCode, userCode, verificationUri, verificationUriComplete, expiresIn, interval }.
• POST /device-token — poll with deviceCode until the browser user approves, denies, or the session expires.

/device-authorize does not require a client-auth JWT. The application opts in with a Layer 3 DEVICE_CODE ReturnRule, and the user completes ordinary Sudomimus authentication in via.sudomimus.com. After /device-token succeeds, use Connect token operations for refresh, logout, introspection, and revocation. See Device authorization flow.

native-api.sudomimus.com

For native clients that cannot host a browser-based redirect, this surface offers two one-shot endpoints:

• POST /direct-issue/steam-ticket — a game with a Steamworks ticket exchanges it directly for { accessToken, refreshToken }.
• POST /direct-issue/access-key — a CLI or service with a pre-issued AccessKey credential exchanges it directly for { accessToken, refreshToken }.

Neither requires a client-auth JWT — the Steam ticket and the AccessKey secret are each their own credential. See Native flows.

oidc.sudomimus.com

A standard OpenID Connect provider. Hosts:

• GET /.well-known/openid-configuration
• GET /.well-known/jwks.json
• GET /authorize (with PKCE, S256 only)
• POST /token
• GET /userinfo, POST /userinfo
• GET /end-session

Supported grants: authorization_code, refresh_token. Supported client authentication: private_key_jwt, client_secret_basic, and client_secret_post (confidential-client options) and none + PKCE (the public-client option). See OIDC flow.

A typical request flow

A web application using the Connect protocol:

   Browser ──────────────► via.sudomimus.com
                              │
                              ▼  user completes the challenge
                              │
                         confirmation-key
                              │
App backend ─────────────► connect-api.sudomimus.com
                              │
                              ▼
                       signed tokens returned
                              │
                              ▼
                App backend verifies tokens (via /info)

The browser and the application backend each talk to a different surface; Sudomimus stitches the two halves together internally, so the application never has to handle the user’s raw authentication material.

A public CLI using device authorization starts at device-api, sends the user to via.sudomimus.com/device, then keeps polling device-api until approval returns tokens. A game using Steam direct-issue collapses the login to a single round trip against native-api. An OIDC relying party talks only to oidc.sudomimus.com; the user is still authenticated via via.sudomimus.com underneath, but the RP does not see it.

Everything else is internal

These five surfaces are the only supported integration points. Sudomimus runs other services behind them — but they are internal to the platform and unreachable from outside it, so there is nothing else for an integration to call. If a flow you need isn’t expressed through one of the five surfaces above, it isn’t an integration point.