This document describes the authentication and authorization flows implemented in the Axum-based authentication API. The system supports password-based authentication, email verification, two-factor authentication (2FA), Google OAuth login, JWT session management, and logout via token revocation.
Create a new user account using email and password credentials and initiate email verification.
Client submits POST /register with:
nameemailpasswordServer normalizes the email (lowercase).
Server checks if a user with the email already exists.
Password is hashed using Argon2:
A new user record is created with:
password_hash (Argon2)email_verified = falseemail_token (UUID verification token)A verification email is sent containing the verification token.
A JWT is issued immediately after registration.
Confirm ownership of the email address associated with a user account.
User clicks verification link containing token.
Client requests GET /verify-email?token=...
Server:
email_verification tableIf valid:
Authenticate a user using email and password credentials.
Client submits POST /login with:
emailpasswordServer fetches the user by email.
Server verifies password using Argon2:
If password verification fails → unauthorized
If user does not require 2FA:
If user requires 2FA:
Add a second authentication factor for high-risk or protected accounts.
Triggered automatically during login if requires_2fa = true.
Server generates:
Code is delivered via configured channel (email/SMS/etc).
Client receives:
temp_tokenuser_idClient submits POST /verify-2fa with:
user_idtemp_tokencodeServer verifies:
On success:
Authenticate users using Google as an identity provider.
Client submits POST /login/google with:
id_tokenServer verifies token with Google:
GOOGLE_CLIENT_ID)Server extracts verified email.
User lookup:
If user exists → continue
If not → create user with:
email_verified = trueGOOGLE_ACCOUNT)JWT is issued.
Rotate JWTs without requiring re-authentication.
Client submits POST /refresh with Bearer token.
Server verifies JWT.
If valid:
Invalidate an active JWT before its expiration.
POST /logout with Bearer token.Allow users to request a new email verification link.
Client submits POST /resend-verification.
Server enforces rate limiting via Redis.
If user exists and is unverified:
| Mechanism | Purpose |
|---|---|
| Argon2 | Password hashing |
| JWT | Stateless session tokens |
| Redis | Token revocation & rate limiting |
| UUID tokens | Email verification |
| 2FA codes | Secondary authentication factor |
| Google OAuth | Federated identity |