---
title: Choose an integration path
description: Choose between Connect, OIDC, device authorization, and native
  direct-issue, then see which public Sudomimus services that path uses.
editUrl: true
head: []
template: doc
sidebar:
  order: 2
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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](/en-us/sdk/overview/). Next.js, React Router, Nuxt, and Django server applications can use a [framework SDK](/en-us/frameworks/overview/) to handle Connect callbacks and sessions. If you are building a web application with Connect, follow [Your first login](/en-us/getting-started/quickstart/) 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](/en-us/getting-started/quickstart/) |
| **OIDC** | Frameworks and partner systems that already speak OpenID Connect | Authorization code + PKCE | [OIDC flow](/en-us/oidc/flow/) |
| **Device authorization** | CLIs, launchers, terminal tools, and public clients without a client secret | `device-authorize → browser approval → device-token` | [Device authorization flow](/en-us/device/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](/en-us/native/overview/) |

:::tip[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](/en-us/ai/cli/) instead.
:::

:::note[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.
:::

:::note[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.
:::

:::note[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](/en-us/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](/en-us/guides/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](/en-us/device/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](/en-us/native/overview/) 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](/en-us/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.

```mermaid
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.