Skip to content

Auth API Route Reference

This page maps the current route groups exposed by seamless-auth-api.

It is not a replacement for the generated OpenAPI document, but it gives you a reliable top-level map of the auth server surface as it exists in the source repo today.


Group Routes Purpose
Authentication /login, /logout, /refresh Login entry, logout, access refresh
Registration /registration/* New-user registration and phone enrollment
OTP /otp/* Email and phone OTP generation and verification
WebAuthn /webauthn/* Passkey registration and login
Magic Links /magic-link* Magic link request, polling, verification
OAuth /oauth/* External provider login start and callback
TOTP /totp/* TOTP enrollment, login MFA, and step-up verification
Step-up Auth /step-up/* Fresh WebAuthn verification before sensitive actions
Users /users/* Authenticated user profile and credential operations
Organizations /organizations/* Self-service organization and membership operations
Sessions /sessions* Session listing and revocation
Admin /admin/* Admin users, import, enrollment, reports, audit, orgs
Internal /internal/* Metrics, grouped events, login stats, anomalies
System Config /system-config/* Roles, runtime config, and OAuth providers
JWKS /.well-known/jwks.json Public JWKS endpoint
Health /health/* Status and version probes

Method Path Purpose
POST /login Start login using email or phone
DELETE /logout Logout the current session
DELETE /logout/all Logout every session owned by the current user
POST /refresh Refresh access state using a valid refresh token state

POST /refresh is the supported refresh method. The route explicitly rejects other HTTP methods.


Method Path Purpose
POST /registration/register Register a new user
POST /registration/phone Add a phone to the signed-in user and send an OTP
POST /registration/phone/verify Verify that phone with the OTP

/registration/phone and /registration/phone/verify require an access token. The OTP is sent only when the phone is new or not yet verified.


Method Path Purpose
GET /otp/generate-email-otp Generate registration email OTP
GET /otp/generate-phone-otp Generate registration phone OTP
GET /otp/generate-login-email-otp Generate login email OTP
GET /otp/generate-login-phone-otp Generate login phone OTP
POST /otp/verify-email-otp Verify registration email OTP
POST /otp/verify-phone-otp Verify registration phone OTP
POST /otp/verify-login-email-otp Verify login email OTP
POST /otp/verify-login-phone-otp Verify login phone OTP

These routes use ephemeral auth state during in-progress auth flows.


Method Path Purpose
GET /webauthn/register/start Start passkey registration
POST /webauthn/register/finish Finish passkey registration
POST /webauthn/login/start Start passkey login
POST /webauthn/login/finish Finish passkey login

Registration start accepts requestPrf=true or requirePrf=true query flags. Assertion start can accept an optional PRF request body. The auth server verifies the passkey assertion but does not store or return PRF output.

Both registration routes require an access session. POST /webauthn/register/finish can answer:

Status Body Cause
400 validation error Request body failed schema validation
401 error No valid access session
403 {"error":"Not allowed"} No user for the session, or no attestation response
403 {"error":"Missing challenge"} No live registration challenge; call /webauthn/register/start again
403 {"error":"Registration failed verification"} The attestation did not verify
403 {"error":"authenticator_not_allowed"} Refused by authenticator_policy: deny list, allow list, or requireKnownAuthenticator
403 {"error":"synced_passkey_not_allowed"} Refused by authenticator_policy.syncedPasskeys: "block"
403 {"error":"prf_required"} Registration started with requirePrf=true and the credential did not report PRF
500 {"error":"An error occured will verifying. Try again"} Attestation verification threw, for example an origin or RP ID mismatch
500 {"error":"Unknown error verifying passkey"} Unexpected server error

authenticator_not_allowed and synced_passkey_not_allowed come from config, not from the user or the device being faulty. Under the default policy neither is returned; they appear once an operator restricts authenticator_policy. See Authenticator Policy for each rule and the order they run in. GET /webauthn/register/start answers 400 {"error":"attachment_not_allowed"} when its attachment query asks for a kind the policy’s pinned attachment excludes.


Method Path Purpose
GET /magic-link Request a magic login link
GET /magic-link/check Poll for confirmation
GET /magic-link/verify/:token Verify a magic link token

Method Path Purpose
GET /oauth/providers List enabled OAuth providers
POST /oauth/:providerId/start Start provider authorization
POST /oauth/:providerId/callback Finish provider login and link user

OAuth provider secrets live in environment variables referenced by system config. Provider access tokens are used only during callback handling and are not returned to browser clients.


Method Path Purpose
GET /totp/status Get TOTP status for the current user
POST /totp/enroll/start Start TOTP enrollment
POST /totp/enroll/verify Verify and enable TOTP enrollment
POST /totp/disable Disable TOTP for the current user
POST /totp/verify-login Verify TOTP during login
POST /totp/verify-mfa Verify TOTP for MFA or step-up authentication

TOTP verification requests use a six-digit code field.


Method Path Purpose
GET /step-up/status Return current session step-up freshness
POST /step-up/webauthn/start Start passkey step-up verification
POST /step-up/webauthn/finish Finish passkey step-up and mark session fresh

These routes require an authenticated access session. TOTP step-up completion is exposed through POST /totp/verify-mfa.


Method Path Purpose
GET /users/me Return authenticated user and credentials
POST /users/credentials Update credential metadata
DELETE /users/credentials Delete a credential
DELETE /users/delete Delete the authenticated user

Method Path Purpose
GET /organizations List organizations for current user
POST /organizations Create organization
GET /organizations/:organizationId Get organization
PATCH /organizations/:organizationId Update organization
POST /organizations/:organizationId/switch Switch active organization
GET /organizations/:organizationId/members List organization members
POST /organizations/:organizationId/members Add organization member
PATCH /organizations/:organizationId/members/:userId Update organization member roles
DELETE /organizations/:organizationId/members/:userId Remove organization member

Organization member inputs accept either userId or email plus optional roles and scopes.


Method Path Purpose
GET /sessions List active sessions for the current user
DELETE /sessions/:id Revoke one session
DELETE /sessions Revoke all sessions for the current user

All admin routes require authenticated admin access. Read routes accept admin, admin:read, or admin:write; write routes accept admin or admin:write. Routes marked step-up also need a fresh step-up on the current session (see Step-up Authentication).

Method Path Access Purpose
GET /admin/users admin read List users
POST /admin/users admin write Create user
DELETE /admin/users admin write Delete user
POST /admin/users/import admin write Import up to 200 users from another system
GET /admin/users/:userId admin read Get user detail
PATCH /admin/users/:userId admin write Update user
GET /admin/users/:userId/anomalies admin read Get anomalies for a user
POST /admin/users/:userId/recovery/device-replacement admin write, step-up Prepare user for device replacement
GET /admin/enrollment admin read Passkey enrollment progress per user
POST /admin/enrollment/invites admin write Email users a notice to enroll a passkey
GET /admin/reports/authentication-coverage admin read Authentication coverage report, JSON or CSV
GET /admin/review-accounts admin read App store review account status and recent use
GET /admin/auth-events admin read Query auth events
GET /admin/auth-events/export admin read, step-up Export audit events in a period as NDJSON
GET /admin/auth-events/integrity admin read Verify the audit event hash chain
GET /admin/credential-count admin read Get credential counts
GET /admin/sessions admin read List all sessions
GET /admin/sessions/:userId admin read List sessions for one user
DELETE /admin/sessions/by-id/:id admin write Revoke one session by session ID
DELETE /admin/sessions/:userId/revoke-all admin write Revoke all sessions for one user
GET /admin/organizations admin read List organizations
POST /admin/organizations admin write Create organization
GET /admin/organizations/:organizationId admin read Get organization
PATCH /admin/organizations/:organizationId admin write Update organization
DELETE /admin/organizations/:organizationId admin write Delete organization
GET /admin/organizations/:organizationId/members admin read List organization members
POST /admin/organizations/:organizationId/members admin write Add organization member
PATCH /admin/organizations/:organizationId/members/:userId admin write Update organization member
DELETE /admin/organizations/:organizationId/members/:userId admin write Remove organization member
PUT /admin/organizations/:organizationId/oauth-providers/:providerId/retirement admin write Retire an OAuth provider for the organization
DELETE /admin/organizations/:organizationId/oauth-providers/:providerId/retirement admin write Restore a retired OAuth provider

The device-replacement recovery route requires fresh step-up authentication and returns counts for revoked sessions, removed passkeys, and disabled TOTP credentials.

POST /admin/users/import creates or updates users matched on the source system id, then on email. It carries no credentials, refuses admin roles, applies each row on its own, and writes nothing with dryRun. seamless migrate csv calls it; see Migrate Users.

POST /admin/enrollment/invites takes userIds (up to 200) or an organizationId, whose members at or below status are invited 200 at a time, skipping anyone invited in the last day. It answers 409 when no sign-in method other than passkey is enabled.

Retiring a provider makes its callback answer 403 with code: oauth_provider_retired for the organization’s members and revokes every live session of every member. Repeating the call revokes nothing. The DELETE undoes it, is idempotent, and accepts the id of a provider that no longer exists.

GET /admin/reports/authentication-coverage takes from and to (UTC dates, both included, default the last 90 days), bucket (week or month, default month), organizationId, and format=csv for a text/csv copy. It answers 404 when organizationId names no organization.

GET /admin/auth-events/export takes optional from and to timestamps and streams application/x-ndjson: one event per line in chain order, then a manifest line with the count, the first and last seq, the anchor hash, and the last hash. A file that does not end with the manifest is incomplete.

Deleting an organization also deletes every membership in it, in one transaction. The member accounts themselves are not deleted. Sessions scoped to the organization stay active with no organization, though an access token issued before the deletion carries the old organization ID until it expires. There is no way to delete an organization through the user-facing /organizations routes; deletion is admin only.

Paging and filtering the admin collections

Section titled “Paging and filtering the admin collections”

The five admin list routes take a window and return total. total counts every row matching the filter, not the rows in the returned page, so a caller can tell whether there is another page to ask for.

Route limit offset Filters
/admin/organizations 1 to 100, default 50 default 0 search over name and slug, case-insensitive
/admin/sessions 1 to 100, default 50 default 0 none
/admin/auth-events 1 to 100, default 10 default 0 userId, actorUserId, sessionId, type, from, to
/admin/users default 50 default 0 search over email and phone, case-insensitive
/admin/enrollment 1 to 100, default 50 default 0 organizationId, status (none, one, two_or_more), imported, search over email

On /admin/enrollment, summary counts every user matching organizationId, imported, and search whatever status, while users and total describe the filtered page.

Sending no parameters returns the first page, not the whole collection. A deployment with more rows than the default receives only that first page, which is what total is for.

/admin/users is the exception to the rest of this table: it reads these parameters but does not declare them, so they do not appear in openapi.json and a generated client will not know they exist. It also applies no maximum to limit. The other three validate the window and reject one outside the allowed range with a 400.


These endpoints are especially important for the admin dashboard.

Method Path Purpose
GET /internal/auth-events/summary Event summary metrics
GET /internal/auth-events/timeseries Event timeseries metrics
GET /internal/auth-events/login-stats Login success/failure stats
GET /internal/auth-events/grouped Grouped auth event summaries
GET /internal/security/anomalies Suspicious activity feed
GET /internal/metrics/dashboard Dashboard summary metrics

Method Path Purpose
GET /system-config/public Read enabled login methods (unauthenticated)
GET /system-config/roles Get available roles
GET /system-config/admin Read current system configuration
PATCH /system-config/admin Update system configuration
GET /system-config/oauth-providers List configured OAuth providers
POST /system-config/oauth-providers Add an OAuth provider
PATCH /system-config/oauth-providers/:id Update an OAuth provider
DELETE /system-config/oauth-providers/:id Remove an OAuth provider

GET /system-config/public needs no session. The other routes require an access token with admin:read (reads) or admin:write (writes).

System config includes roles, token TTLs, login methods, OAuth providers, lockout policy, passkey fallback policy, WebAuthn relying party ID, and allowed origins.

For field-level behavior, see System Config Reference.


Method Path Purpose
GET /.well-known/jwks.json Publish public keys for verification

For token and JWKS details, see Cookie, Session, And Token Reference.


Method Path Purpose
GET /health/status Health check endpoint
GET /health/version API version information