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.
Route Groups
Section titled “Route Groups”| 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 |
Authentication
Section titled “Authentication”| 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.
Registration
Section titled “Registration”| 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.
WebAuthn
Section titled “WebAuthn”| 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.
Magic Links
Section titled “Magic Links”| 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.
Step-up Authentication
Section titled “Step-up Authentication”| 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 |
Organizations
Section titled “Organizations”| 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.
Sessions
Section titled “Sessions”| 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.
Internal
Section titled “Internal”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 |
System Config
Section titled “System Config”| 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.
Health
Section titled “Health”| Method | Path | Purpose |
|---|---|---|
GET |
/health/status |
Health check endpoint |
GET |
/health/version |
API version information |