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

POST · /api/v1/auth/login

Validates credentials and issues a signed JWT token if the user is active and correctly authenticated.

🛡️ 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.

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

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

// 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']);
});