User and System Journeys

Concise route sequences for supported AuthOS authentication and administration flows.

AuthOS release 0.8.5 API v1 Latest-only documentation
Updated Aug 2, 2026
On this page

AuthOS supplies APIs, hosted lite-client routes, and SDK adapters. Your product owns its application UI. The sequences below name only the AuthOS requests that participate in each journey; see the focused reference pages for payloads.

Password sign-in

  1. Register with POST /api/auth/register or sign in with POST /api/auth/login.
  2. When email verification is required, the emailed link reaches GET /auth/verify-email.
  3. When MFA is required, complete POST /api/auth/mfa/verify.
  4. Select a tenant with POST /api/organizations/{org_slug}/select when the session must be scoped to an organization.
  5. Refresh with POST /api/auth/refresh and end the session with POST /api/auth/logout.

Store refresh tokens only in an appropriate secure store. Browser adapters must not expose service API keys or platform credentials.

OAuth sign-in

  1. Navigate to GET /auth/{provider} with the required service and redirect context.
  2. The provider returns to GET /auth/{provider}/callback.
  3. AuthOS validates state and exchanges the provider response before issuing the AuthOS session.

Admin-provider authorization uses the separate /auth/admin/{provider} route pair. Do not interchange the two flows.

Passwordless sign-in

  • Magic links begin with POST /api/auth/magic-link/request and are verified by GET /api/auth/magic-link/verify.
  • Passkey authentication uses POST /api/auth/passkeys/authenticate/start followed by POST /api/auth/passkeys/authenticate/finish.

Passkey enrollment is a separate authenticated user flow under /api/auth/passkeys/register/*.

Device authorization

  1. The device requests a code with POST /auth/device/code.
  2. A user reviews the code through the hosted activation flow, which submits POST /auth/device/verify.
  3. The device polls POST /auth/token until authorization succeeds, is denied, or expires.

The device code is not a bearer access token and must not be logged.

Tenant administration

An authenticated tenant administrator works through organization-scoped routes for members, services, roles, invitations, webhooks, SIEM, domains, and upstream providers. Every resource identifier is checked against the organization in the URL. A cross-tenant identifier is returned as not found rather than revealing ownership.

Service-to-service access

Backends authenticate with X-Api-Key only on the /api/service/* surface. Service keys belong in server-side secret storage and must never be shipped in React, Vue, browser, or mobile bundles.

Platform operation

Platform-owner routes live under /api/platform/* and are distinct from tenant administration. Promotion, impersonation, bootstrap changes, and destructive actions require their dedicated routes and authorization checks. Keep platform credentials out of tenant tooling.

For the exhaustive method/path inventory, use the Complete Endpoint Catalog.