Skip to main content
Flowxi authentication is designed for financial-grade security, deterministic behavior, and frontend-safe integration. It relies on Laravel Sanctum personal access tokens (Bearer tokens) and enforces strict guarantees around:
  • Anti-enumeration
  • Device-bound sessions
  • Aggressive rate limiting
  • Optional but first-class 2FA (TOTP)
  • Full localization of all responses
This document describes the authentication system as implemented, based on controllers, middleware, caching, and validation logic.

​
Authentication Model

Flowxi uses token-based authentication. After a successful authentication, the API returns:
  • access_token (string)
  • token_type = Bearer
All protected endpoints require the token: 
Authorization: Bearer <access_token>
Tokens are:
  • Personal
  • Revocable
  • Bound to a specific device

​
Localization (Global)

Before any authentication logic runs, the locale is resolved by middleware. Resolution order:
  1. X-App-Locale header
  2. Accept-Language
  3. user.locale (authenticated requests only)
  4. Fallback: fr
The resolved locale applies to:
  • message fields
  • Validation errors
  • Authentication errors
  • Emails sent during the request
Frontend rule: Client logic must rely on code, never on translated message values.

​
Supported Authentication Flows

Flowxi exposes three primary authentication entry points.
Email-first flow. Password is defined after verification.

​
Flow

  1. Magic link is sent by email
  2. User clicks the link
  3. Password is set
  4. Account becomes active
  5. Token is issued

​
Endpoints

  • POST /api/v1/auth/register-email
  • POST /api/v1/register-email/resend
  • POST /api/v1/auth/register/set-password

​
Security Properties

  • Anti-enumeration
  • Single-use expiring links
  • Transactional activation
  • Fully localized emails

​
2) Registration via Email Code (OTP)

Code-based verification before password setup.

​
Flow

  1. 6-digit code is sent by email
  2. Code is verified
  3. Password is set
  4. Account becomes active
  5. Token is issued

​
Endpoints

  • POST /api/v1/register-email-code/send
  • POST /api/v1/register-email-code/resend
  • POST /api/v1/register-email-code/verify
  • POST /api/v1/register-email-code/set-password

​
Security Properties

  • OTP codes stored hashed only
  • Expiration enforced at database level
  • Strict rate limits on:
    • Send
    • Verify
    • Set-password
  • Transactional activation
  • Locale persisted on the user model

​
3) Login (Email + Password)

Standard login with optional 2FA challenge.

​
Endpoint

  • POST /api/v1/auth/login

​
Required Fields

  • email
  • password
  • device_id
  • device_type
  • device_name

​
Optional Fields

  • country

​
Anti-Enumeration

The login endpoint never reveals whether:
  • An email exists
  • The password is incorrect
  • The account is inactive
All such cases return:
  • HTTP 401
  • code: INVALID_CREDENTIALS
This behavior is mandatory and must not be bypassed.

​
Rate Limiting

Authentication endpoints are aggressively rate-limited.

​
Examples

  • Login: per email + ip
  • OTP send / resend: per email + ip
  • OTP verify / set-password: stricter limits
  • 2FA enable / disable / verify: per user + ip
Rate limits apply even if the user does not exist.

​
Device-Based Sessions

Flowxi enforces device-level sessions.

​
Rules

  • Exactly one active token per device_id
  • Re-login on the same device:
    • Revokes the previous token
    • Issues a new one
  • Other devices remain active
Enforced transactionally using:
  • Token deletion
  • PostgreSQL advisory locks

​
Login Without 2FA

If 2FA is disabled:
  1. Credentials are verified
  2. Existing token for the same device is revoked
  3. A new token is issued

​
Response Includes

  • access_token
  • account_status
  • user_id

​
Login With 2FA Enabled

Login becomes a two-step process.

​
Step 1: Login

POST /api/v1/auth/login

​
Response

  • mfa_required: true
  • challenge_id
  • otp_type: totp
  • expires_in
No token is issued at this stage. The challenge is stored in cache and bound to:
  • IP address
  • User-Agent
  • device_id
TTL is fixed and non-extendable.

​
Step 2: Verify Login 2FA

POST /api/v1/auth/2fa/verify-login

​
Input

  • challenge_id
  • code (TOTP)

​
Rules

  • Maximum 5 attempts per challenge
  • Strict IP + User-Agent matching
  • Challenge is consumed on success

​
On Success

  • Previous token for the device is revoked
  • A new token is issued

​
Session & Device Management

All endpoints below require authentication.

​
Logout (Current Session)

POST /api/v1/auth/logout
  • Deletes the current token only
  • Other devices remain active

​
Logout a Specific Device

POST /api/v1/auth/logout-device
  • Requires device_id
  • Revokes the token associated with that device

​
List Active Devices

GET /api/v1/auth/devices Returns:
  • Device metadata
  • IP address
  • User-Agent
  • Country
  • Creation timestamp
  • Last-used timestamp
  • Current device indicator
Legacy tokens without device_id are excluded.

​
Two-Factor Authentication (2FA)

Flowxi supports TOTP-based 2FA. All endpoints below are protected.

​
2FA Status & Enrollment

GET /api/v1/auth/2fa/status

​
Behavior

  • If enabled:
    • enabled: true
    • Secret and QR code are never returned
  • If disabled:
    • A pending secret is generated in cache
    • Response includes:
      • secret
      • otpauth_uri
      • expires_in
The secret is not stored in database at this stage.

​
Enable 2FA

POST /api/v1/auth/2fa/enable

​
Input

  • code (TOTP)

​
Rules

  • Code is verified against the pending secret
  • On success:
    • Secret is committed to database
    • twofa_enabled is set to true
    • Pending secret is cleared
  • Does not force logout

​
Disable 2FA

POST /api/v1/auth/2fa/disable

​
Input

  • code (TOTP)

​
Rules

  • Code is verified against the stored secret
  • On success:
    • Secret is cleared
    • 2FA is disabled
  • Does not force logout

​
Step-Up Verification

POST /api/v1/auth/2fa/verify Used for sensitive actions.
  • Verifies TOTP code
  • Does not issue a token
  • Updates twofa_last_verified_at if present

​
Guarantees

Flowxi authentication guarantees:
  • Deterministic error codes
  • Strict anti-enumeration
  • Device-level session isolation
  • No silent token duplication
  • Full localization
  • No secret leakage during 2FA enrollment
All rules described in this document are enforced in code and validated in production scenarios.