Skip to content

API Reference

All 20 endpoints exposed by warden.router, organized by sub-router. Mount with whatever prefix you like — examples below assume prefix="/auth" as in the Quickstart.

Auth

Method Path Auth required Description
POST /register No Registration
POST /verify-email No Verification — link mode
POST /verify-otp No Verification — OTP mode
POST /resend-verification No Verification
POST /login No Login
POST /logout Yes Logout
POST /refresh No¹ Refresh
POST /forgot-password No Password reset
POST /reset-password No Password reset — link mode
POST /reset-password-otp No Password reset — OTP mode
POST /change-password Yes Password reset
POST /set-password Yes Password reset — OAuth-only accounts

¹ Authenticated implicitly via the refresh token in the request body, not a Bearer header.

MFA (/mfa prefix)

Method Path Auth required Description
POST /mfa/setup Yes MFA
POST /mfa/confirm Yes MFA
POST /mfa/disable Yes MFA

OAuth (/oauth prefix)

Method Path Auth required Description
GET /oauth/accounts Yes Account linking
GET /oauth/{provider}/authorize Optional² OAuth overview
POST /oauth/{provider}/callback No OAuth overview
POST /oauth/{provider}/connect Yes OAuth overview
DELETE /oauth/{provider}/disconnect Yes OAuth overview

² A valid Bearer token changes this endpoint's behavior from "login" to "connect" mode — see OAuth overview.

Authentication header

Every authenticated endpoint expects:

Authorization: Bearer <access_token>

Exception → status code reference

Every flow raises a typed AuthError subclass; the router converts it to the matching HTTPException automatically.

Exception Status Exception Status
EmailAlreadyExists 409 InvalidToken 400
UsernameAlreadyExists 409 TokenExpired 400
PhoneAlreadyExists 409 TokenRevoked 401
WeakPassword 422 TokenAlreadyUsed 400
InvalidEmail 422 SamePassword 422
AlreadyVerified 409 PasswordNotSet 400
RateLimited 429 PasswordAlreadySet 400
InvalidCredentials 401 UserNotFound 404
AccountInactive 403 ForbiddenError 403
AccountLocked 423 MFANotEnabled 400
EmailNotVerified 403 MFAAlreadyEnabled 409
InvalidMFACode 401 InvalidBackupCode 401
MFARequired 403 OAuthProviderNotConfigured 404
OAuthStateMismatch 400 EmailAlreadyRegistered 409
OAuthCodeExchangeFailed 502 ProviderAlreadyLinked 409
OAuthUserInfoFailed 502 LastLoginMethod 400
OAuthAccountNotFound 404

Every response body follows FastAPI's standard error shape:

{ "detail": "human-readable message" }