Skip to content

Routes

bluefox_auth.routes

All routes are mounted under the configured prefix (default /auth).

POST /register

Create a new user account.

Request body (RegisterRequest): 

{ "email": "user@example.com", "password": "strong-password" }

Response (201): UserResponse

Errors:

  • 409 — Email already registered
  • 422 — Invalid email, password too short (< 8 chars), or password exceeds 72 bytes

POST /login

Authenticate with email and password. Returns tokens in the JSON body and sets HttpOnly cookies.

Request body (LoginRequest): 

{ "email": "user@example.com", "password": "my-password" }

Response (200): TokenResponse 

{ "access_token": "...", "refresh_token": "...", "token_type": "bearer" }

Cookies set: bf_access_token, bf_refresh_token, bf_csrf_token

Errors:

  • 401 — Invalid credentials (same message for wrong email or wrong password)

POST /refresh

Rotate a refresh token. Accepts the token from JSON body or from the refresh cookie.

Request body (optional, RefreshRequest): 

{ "refresh_token": "..." }

If no JSON body is provided, the refresh token is read from the bf_refresh_token cookie. When using cookie transport, CSRF validation is required — send the X-CSRF-Token header.

Response (200): TokenResponse

Errors:

  • 401 — Invalid, expired, or revoked refresh token; token reuse detected
  • 403 — Missing CSRF token (cookie transport only)

POST /logout

Revoke the token family and clear auth cookies. Works with or without authentication.

Request body (optional, LogoutRequest): 

{ "refresh_token": "..." }

If no JSON body is provided, the refresh token is read from the cookie. Invalid tokens are silently ignored.

Response (200): 

{ "message": "Logged out" }

GET /me

Return the current user's profile. Requires authentication.

Response (200): UserResponse 

{
  "id": 1,
  "email": "user@example.com",
  "is_active": true,
  "is_superuser": false,
  "email_verified": false
}

Errors:

  • 401 — Not authenticated or user inactive

POST /password-reset

Request a password reset email. Always returns the same response regardless of whether the email exists.

Request body (PasswordResetRequest): 

{ "email": "user@example.com" }

Response (200): MessageResponse

Errors:

  • 501 — Password reset not configured (no password_reset_send_fn provided)

POST /password-reset/confirm

Confirm a password reset with the token from the email.

Request body (PasswordResetConfirm): 

{ "token": "...", "new_password": "new-strong-password" }

Response (200): MessageResponse

Errors:

  • 400 — Invalid, expired, or already-used reset token
  • 422 — Password too short or exceeds 72 bytes

POST /email-verification

Request a verification email. Requires authentication. Short-circuits if already verified.

Response (200): MessageResponse

Errors:

  • 401 — Not authenticated
  • 501 — Email verification not configured (no email_verify_send_fn provided)

POST /email-verification/confirm

Confirm email verification with the token from the email.

Request body (EmailVerificationRequest): 

{ "token": "..." }

Response (200): MessageResponse

Errors:

  • 400 — Invalid, expired, or already-used verification token