> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowxi.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

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:

```http theme={null}
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**.

***

## 1) Registration via Magic Link

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**.