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.

Most integrations should start from the SDK overview after choosing a path. The SDK pages map each path to the TypeScript, Python, and C# packages; this page explains which protocol shape you need.

Path	Best fit	Protocol shape	Start here
Connect	Web applications and custom browser sign-in	establish → authenticate → redeem, then Session API 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.

Device browser approval

The device approval page currently supports email OTP and passkeys. Choose Connect or OIDC if your application needs OAuth, Steam OpenID, or enterprise sign-in.

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

The six surfaces

Domain	Audience	Protocol
connect-api.sudomimus.com	Application backend	Connect protocol (JSON over HTTPS)
session-api.sudomimus.com	Applications holding ordinary refresh tokens	Session lifecycle (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
• Localized application metadata: POST /info

/establish requires 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). /redeem and /status-poll are authorized by Inquiry keys; /info is public.

See Connect flow for end-to-end examples.

session-api.sudomimus.com

The HTTPS API for the ordinary application refresh-token lifecycle after Connect, device authorization, or native direct-issue has returned { accessToken, refreshToken }.

• GET /applications/{applicationAnchor}/jwks.json returns the public keys used to verify application tokens by kid.
• POST /refresh rotates a refresh token and issues a new access token.
• POST /introspect checks whether an access token’s backing session is still active.
• POST /logout terminally revokes one ApplicationSession.
• POST /revoke-all ends every session for one application-visible subject.

/refresh, /introspect, and /logout are self-authenticating with the presented token. /revoke-all requires a client-auth JWT with aud = "sudomimus-session". See Managing sessions.

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 Session API 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 Session JWKS)

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 six 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 six surfaces above, it isn’t an integration point.