Quickstart

This page walks through the smallest possible integration: pointing a web application at Sudomimus and obtaining a verified user identity.

Recommended: use an official SDK

The fastest way to integrate the browser login round-trip is via an official SDK — install @sudomimus/connect and call typed methods (establish, redeem, verifyAccessToken) instead of building raw HTTP requests by hand. Use the Session API for refresh after tokens are issued.

Install the SDK

Using an AI coding assistant?

Use the Sudomimus CLI when an assistant needs to operate Sudomimus directly. It exposes shell commands and JSON output while keeping login in your browser through the device authorization flow.

Use the CLI with AI

Not building a web app? Pick the right guide:

Sudomimus CLIShell-friendly account and developer operations for AI agents, local automation, and source checkouts.

Native clientsDesktop apps, games via Steam, and CLI tools — including the browser Errand for consent and profile completion.

OIDC relying partiesStandard OpenID Connect — authorization_code + PKCE.

Prerequisites

1. Create or join an organization at with.sudomimus.com. The developer self-serve portal is organization-based: applications and sectors live inside an organization, so you need one before you can create an application. Most accounts create their first organization on the spot (the form pre-fills a suggested name); if a teammate already runs one, have them invite you instead. The /applications and /sectors pages redirect to /organizations until you belong to one.

2. Create your application inside that organization. When you create the application you receive:

   • The applicationAnchor — a stable, lowercase-kebab identifier (e.g. my-app), the public name of your application across the API.
   • The client-auth private key — shown once at creation, used to sign /establish requests. Store it like any production secret.
   • A per-application Session JWKS URL at https://session-api.sudomimus.com/applications/{applicationAnchor}/jwks.json, used to verify access and refresh tokens by kid. The portal’s Signing keys tab manages rotation; application creation does not return a one-off signing PEM.

3. Add at least one Return Rule of type CALLBACK, listing the hostnames you will redirect users back to. The concrete callbackUrl is supplied per inquiry on /establish; the rule just gates which hostnames are allowed.

4. Add at least one Authentication Rule (e.g. PASSKEY_USERNAMELESS, PASSKEY_REASONED, or EMAIL_VERIFICATION) and one Realize Rule (e.g. EMAIL with allowedEmails: ["*"] for a public sign-up). Rules are allowlist-only with default-deny — an application with zero rules in any layer cannot be used.

5. Take the application live. New applications start in DRAFT. After configuring the rules and saving the credentials, an organization OWNER must choose Go live in the With portal to change it to ACTIVE. Saving rules does not activate it. Follow Take an application live for readiness and activation checks. If /establish returns ApplicationNotActive, check the application lifecycle and the availability of its organization and sector before retrying.

The four phases

Every authentication round-trip through Connect has three phases, followed by the shared Session API refresh phase:

1. Establish — your application backend asks Connect to start an authentication session and gets back a session reference (exposureKey + hiddenKey).
2. Authenticate — your application sends the user to via.sudomimus.com with the exposureKey; the user completes a passkey or email-OTP challenge there.
3. Redeem — once via.sudomimus.com hands control back via your callback URL (with exposure-key + confirmation-key in the query string), your backend exchanges the three keys at Connect for a signed access token and refresh token.
4. Refresh — your backend calls Session API to exchange the refresh token for a fresh access token whenever the current one nears expiry.

See the Connect flow for the full request shapes and how Connect, via.sudomimus.com, and your application interact.

Next steps

Connect flowEnd-to-end curl, Node.js, Python, and Go examples for the Connect API.

The three-key modelHow a single login proves itself across exposureKey, hiddenKey, and confirmationKey.

Managing sessionsRefresh, introspect, logout, and revoke-all — the lifecycle after the initial login.

Sudomimus CLIA command-line control surface for AI assistants and local automation.