---
title: Quickstart
description: A minimal end-to-end integration with the Sudomimus Connect API.
editUrl: true
head: []
template: doc
sidebar:
  order: 3
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

import { CardGrid, LinkButton, LinkCard } from "@astrojs/starlight/components";

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

:::tip[Recommended: use an official SDK]
The fastest way to integrate is via an official SDK — install [`@sudomimus/connect`](/en-us/reference/sdks/) and call typed methods (`establish`, `redeem`, `refresh`, `verifyAccessToken`) instead of building raw HTTP requests by hand.

<LinkButton href="/en-us/reference/sdks/" variant="primary" icon="right-arrow">Install the SDK</LinkButton>
:::

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

<LinkButton href="/en-us/ai/cli/" variant="secondary" icon="right-arrow">Use the CLI with AI</LinkButton>
:::

Not building a web app? Pick the right guide:

<CardGrid>
<LinkCard
    title="Sudomimus CLI"
    description="Shell-friendly account and developer operations for AI agents, local automation, and source checkouts."
    href="/en-us/ai/cli/"
/>
<LinkCard
    title="Native clients"
    description="Desktop apps, games via Steam, and CLI tools — including the browser Errand for consent and profile completion."
    href="/en-us/native/overview/"
/>
<LinkCard
    title="OIDC relying parties"
    description="Standard OpenID Connect — authorization_code + PKCE."
    href="/en-us/oidc/flow/"
/>
</CardGrid>

## Prerequisites

1. **Create or join an organization at [`with.sudomimus.com`](https://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](/en-us/application-rules/return-rules/)** 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](/en-us/application-rules/authentication-rules/)** (e.g. `PASSKEY_USERNAMELESS`, `PASSKEY_REASONED`, or `EMAIL_VERIFICATION`) and one [Realize Rule](/en-us/application-rules/realize-rules/) (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](/en-us/connect/flow/) for the full request shapes and how Connect, `via.sudomimus.com`, and your application interact.

## Next steps

<CardGrid>
<LinkCard
    title="Connect flow"
    description="End-to-end curl, Node.js, Python, and Go examples for the Connect API."
    href="/en-us/connect/flow/"
/>
<LinkCard
    title="The three-key model"
    description="How a single login proves itself across exposureKey, hiddenKey, and confirmationKey."
    href="/en-us/connect/three-key-model/"
/>
<LinkCard
    title="Managing sessions"
    description="Refresh, introspect, logout, and revoke-all — the lifecycle after the initial login."
    href="/en-us/guides/managing-sessions/"
/>
<LinkCard
    title="Sudomimus CLI"
    description="A command-line control surface for AI assistants and local automation."
    href="/en-us/ai/cli/"
/>
</CardGrid>