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.

This page is the current capability map for supported integration paths, public service audiences, and protocol responsibilities.

After choosing a protocol path, choose an SDK. Next.js, React Router, Nuxt, and Django server applications can use a framework SDK to handle Connect callbacks and sessions. If you are building a web application with Connect, follow Your first login for the complete setup-to-token tutorial. 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	Complete your first login
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, AccessKeys, or public keys	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.

Public services

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 hosts browser authentication. Your application redirects users to it and does not call its endpoints directly.

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

Three credential-based direct-issue endpoints:

• POST /direct-issue/steam-ticket — a Steamworks ticket.
• POST /direct-issue/access-key — an AccessKey identifier and secret.
• POST /direct-issue/public-key — a signed Ed25519 assertion.

AccessKey and PublicKey support Account, Agent, and Automation principals with independent Layer-1 admission. These endpoints use their own credential proof rather than an application client-auth JWT. See Native flows for configuration and Errand recovery.

oidc.sudomimus.com

A standard OpenID Connect provider. Hosts:

• GET /.well-known/openid-configuration
• GET /.well-known/webfinger
• GET /.well-known/jwks.json
• GET /authorize, POST /authorize
• POST /token
• GET /userinfo, POST /userinfo
• GET /end-session, POST /end-session
• POST /register
• GET /register/{client_id}, DELETE /register/{client_id}
• GET /claim-state, POST /claim-state

Supported grants: authorization_code, implicit, refresh_token. Confidential clients use private_key_jwt, client_secret_basic, or client_secret_post. Public clients use none. Public code-bearing flows require PKCE S256; confidential code-bearing flows should use it. Pure Implicit ignores PKCE. Code + PKCE is the recommended starting point. See OIDC flow.

A typical request flow

The topology below maps each integration path to the public services it uses. Native clients that use browser polling follow the Connect edges, not the Native direct-issue edge.

flowchart LR
    subgraph Paths["Integration paths"]
        Connect["Connect<br/>web apps and confidential browser polling"]
        OIDC["OIDC<br/>relying parties"]
        Device["Device authorization<br/>public clients"]
        Native["Native direct-issue<br/>Steam tickets, AccessKeys, and public keys"]
    end

    subgraph Surfaces["Public Sudomimus services"]
        ConnectAPI["connect-api.sudomimus.com"]
        SessionAPI["session-api.sudomimus.com"]
        Via["via.sudomimus.com"]
        DeviceAPI["device-api.sudomimus.com"]
        NativeAPI["native-api.sudomimus.com"]
        OIDCAPI["oidc.sudomimus.com"]
    end

    Connect -->|establish, redeem, status-poll| ConnectAPI
    Connect -->|hosted authentication| Via
    Connect -->|session operations| SessionAPI

    Device -->|authorize and poll| DeviceAPI
    Device -->|browser approval| Via
    Device -->|after initial issuance| SessionAPI

    Native -->|one-shot credential exchange| NativeAPI
    Native -->|after initial issuance| SessionAPI

    OIDC -->|discovery, authorize, token, userinfo| OIDCAPI
    OIDCAPI -. hosted browser handoff .-> Via

The browser uses via.sudomimus.com, while the application backend calls the API for its integration path. Sudomimus coordinates authentication and token issuance. The application does not 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.