Server Types

AuthResponse

Returned by create_user(), login(), refresh(), verify_magic_link(), and verify_email_otp().

{
    "user": UserResponse,
    "tokens": AuthTokens,
}

{
    "user": UserResponse,
    "tokens": AuthTokens,
}

Field	Type	Description
user	UserResponse	User info
tokens	AuthTokens	Token pair

---

UserResponse

User information. Returned inside AuthResponse and from the current_user dependency.

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "Jane Doe",
    "email_verified": false,
    "avatar_url": null,
    "phone": null,
    "banned": false,
    "roles": ["admin"],
    "created_at": "2026-01-15T10:30:00Z",
    "session_id": "660f9500-f30c-52e5-b827-557766550000"
}

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "Jane Doe",
    "email_verified": false,
    "avatar_url": null,
    "phone": null,
    "banned": false,
    "roles": ["admin"],
    "created_at": "2026-01-15T10:30:00Z",
    "session_id": "660f9500-f30c-52e5-b827-557766550000"
}

Field	Type	Description
id	UUID	User UUID
email	str	Email address
name	str | None	Display name
email_verified	bool	Whether email is verified
avatar_url	str | None	Profile image URL (from OAuth)
phone	str | None	Phone number
banned	bool	Whether the user is banned
roles	list[str]	Assigned roles
created_at	datetime	Account creation time
session_id	UUID | None	Current session ID (from sid JWT claim)

---

AuthTokens

Token pair returned inside AuthResponse.

Field	Type	Description
access_token	str	JWT access token
refresh_token	str	Opaque refresh token
expires_in	int	Access token TTL in seconds

---

SessionResponse

Returned by get_sessions().

Field	Type	Description
id	UUID	Session UUID
user_agent	str | None	Browser/client identifier at login
ip_address	str | None	Client IP at login
created_at	datetime	Session creation time
expires_at	datetime	Session expiration time
revoked	bool	Whether the session is revoked

---

ListUsersResponse

Returned by list_users().

Field	Type	Description
users	list[UserResponse]	Users on the current page
total	int	Total matching users across all pages
limit	int	Page size used
offset	int	Offset used

---

UserDeleted

Event payload for user_deleted.

Field	Type	Description
user_id	UUID	Deleted user’s ID
email	str	Deleted user’s email
timestamp	datetime	When the deletion occurred

---

AuthError

Exception raised by all AuthFort methods on failure.

from authfort import AuthError

try:
    await auth.login("user@example.com", "wrong")
except AuthError as e:
    print(e.message)      # "Invalid credentials"
    print(e.code)         # "invalid_credentials"
    print(e.status_code)  # 401

from authfort import AuthError

try:
    await auth.login("user@example.com", "wrong")
except AuthError as e:
    print(e.message)      # "Invalid credentials"
    print(e.code)         # "invalid_credentials"
    print(e.status_code)  # 401

Field	Type	Description
message	str	Human-readable error message
code	str	Machine-readable error code
status_code	int	HTTP status code

Error Codes

Code	Status	Meaning
invalid_credentials	401	Wrong email or password
user_exists	409	Email already registered
oauth_account	400	Account uses social login
user_banned	403	Account is banned
signup_disabled	403	Public signup is disabled
refresh_token_invalid	401	Refresh token invalid
refresh_token_expired	401	Refresh token expired
user_not_found	404	User not found
invalid_password	400	Old password incorrect (change password)
invalid_reset_token	400	Reset token invalid or expired
oauth_state_invalid	400	Invalid OAuth state
oauth_state_expired	400	OAuth state expired
invalid_email	400	Invalid email address
invalid_verification_token	400	Email verification token invalid or expired
invalid_magic_link	400	Magic link token invalid or expired
invalid_otp	400	OTP code invalid or expired
oauth_no_email	400	OAuth provider did not return an email
oauth_no_user_id	400	OAuth provider did not return a user ID