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 is via an official SDK — install @sudomimus/connect and call typed methods (establish, redeem, refresh, verifyAccessToken) instead of building raw HTTP requests by hand.

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 CLI Shell-friendly account and developer operations for AI agents, local automation, and source checkouts.

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

OIDC relying parties Standard 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.
   • The application’s token-signing public key, which is also accessible at runtime via POST /info and is used to verify access tokens.

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.

The four phases

Every authentication round-trip through the Connect API follows the same four phases:

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 exchanges 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 flow End-to-end curl, Node.js, Python, and Go examples for the Connect API.

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

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

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