> ## Documentation Index
> Fetch the complete documentation index at: https://alan-ramirez-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 🔐 Authentication and RBAC

> Stateless identity management with JWT and role-based access control.

The security core of this API rests on a *stateless* authentication model using **JSON Web Tokens (JWT)** and a strict **Role-Based Access Control (RBAC)** architecture.

## 🔑 Stateless Authentication (JWT)

The authentication flow is centralized in the `AuthController`, designed to be lightweight, secure, and fully adapted to language switching.

<ParamField path="POST" type="/api/v1/auth/login">
  Validates credentials and issues a signed JWT token if the user is active and correctly authenticated.
</ParamField>

### 🛡️ Validation and Security Flow

1. **Credential Verification:** Validates email and encrypted password using Laravel's `Hash` facade.
2. **Logical Deletion Protection:** If the user exists but has been deactivated (Soft Delete), the system blocks access with a `403 Forbidden` code, preventing the token issuance.
3. **Brute Force Prevention:** The route is protected by a perimeter middleware (`throttle:4,1`) that blocks the IP for one minute after 4 failed attempts.

```php theme={null}
// Snippet from AuthController.php validating inactive users
$user = User::withTrashed()->where('email',$request->email)->first();

if ($user->trashed()) {
    $errorMsg =$isEn 
        ? 'Your account is inactive. Contact an administrator.' 
        : 'Tu cuenta está inactiva. Contacta a un administrador.';
    return response()->json(['error' => $errorMsg], 403);
}
```

## 🛂 Role-Based Access Control (RBAC)

Once the token is issued, authorization of protected routes is delegated to the custom `CheckRole` middleware. This component intercepts requests, extracts the authenticated user's profile, and dynamically verifies their privileges.

### 🚦 Interception Logic

The middleware leverages the Many-to-Many relationship between Eloquent's `User` and `Role`. It uses PHP's native *spread* operator (`...$roles`) to receive a variable amount of allowed roles directly from the route definition.

```php theme={null}
// Snippet from CheckRole.php
public function handle(Request $request, Closure $next, ...$roles)
{
    $user = $request->user();

    // Compares the user's role collection against the required roles
    $hasAccess = $user->roles->whereIn('name', $roles)->isNotEmpty();

    if (!$hasAccess) {
        $errorMsg = $isEn 
            ? 'Access denied. Insufficient privileges for this action.' 
            : 'Acceso denegado. Privilegios insuficientes para esta acción.';
            
        return response()->json(['error' => $errorMsg], 403);
    }

    return $next($request);
}
```

### 🛤️ Clean Implementation in the Router

This architecture allows protecting entire groups of endpoints with a declarative and highly readable syntax in the routes file.

```php theme={null}
// Snippet from api.php
// Example: Exclusive access for administrators and auditors
Route::middleware(['auth:api', 'role:admin,auditor'])->group(function () {
    Route::get('audit-logs', [AuditLogController::class, 'index']);
});

// Example: Exclusive access for administrators (Write)
Route::middleware(['auth:api', 'role:admin'])->group(function () {
    Route::post('users', [UserController::class, 'store']);
});
```