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

# 👤 Introduction to the Identity and Access Management System

> IAM Core API - Identity and Access Management (Backend)

Welcome to the documentation of the fourth microservice of the project. My Portfolio's Identity and Access Management System!

This project acts as the centralized backend to manage identities and permissions. It is designed under a strict REST architecture to demonstrate capabilities in API security, role-based access control (RBAC), and relational database design in modern environments.

## 🚀 Features and Backend Architecture

<CardGroup cols={2}>
  <Card title="JWT Security" icon="key">
    Implementation of stateless authentication to secure transactions between the client and the server using JSON Web Tokens.
  </Card>

  <Card title="Access Control (RBAC)" icon="user-check">
    Custom middlewares that intercept and validate granular privileges (`admin`, `auditor`, `operator`) before executing controllers.
  </Card>

  <Card title="Immutable Log" icon="history">
    Transactional event log with JSON fields (`payload`) for historical metadata and IP address anonymization using Traits.
  </Card>

  <Card title="Data Protection" icon="database">
    Implementation of "Soft Deletes" for logical user deletions, maintaining referential integrity without losing history.
  </Card>

  <Card title="RESTful Standardization" icon="network">
    Standardized communication contracts under strict versioning (`/api/v1/`), guaranteeing the secure evolution of interfaces.
  </Card>

  <Card title="Automated Testing" icon="flask-conical">
    Business logic and endpoint coverage using **Pest**, guaranteeing predictable and regression-proof flows.
  </Card>
</CardGroup>

## 🛠️ Tech Stack

| Technology     | Version | Project Purpose                                    |
| :------------- | :------ | :------------------------------------------------- |
| **Laravel**    | `^13.8` | Base framework, MVC routing, and ORM (Eloquent)    |
| **PHP**        | `^8.3`  | Server language with strict typing                 |
| **PostgreSQL** | `17`    | Relational database engine and sequence management |
| **jwt-auth**   | `^2.3`  | Access token generation and validation             |
| **Pest**       | `^4.7`  | Testing framework                                  |

## 💻 Development Commands

Instructions to set up the environment locally (it is assumed that PostgreSQL is running on port `5434`).

```bash theme={null}
# Install dependencies
composer install

# Generate environment variables and keys
cp .env.example .env
php artisan key:generate
php artisan jwt:secret

# Rebuild DB and seed data
php artisan migrate:fresh --seed

# Start local server
php artisan serve

# Run test suite
php artisan test
```

## 📡 API Documentation

All requests to protected routes require the header: `Authorization: Bearer <token>`.

### 🔐 Authentication (`/api/v1/auth`)

| Method | Endpoint  | Description                                    | Access    |
| :----- | :-------- | :--------------------------------------------- | :-------- |
| `POST` | `/login`  | Authenticates credentials and returns the JWT  | Public    |
| `GET`  | `/me`     | Returns the information of the user in session | Protected |
| `POST` | `/logout` | Invalidates the current token in the blacklist | Protected |

### 👥 Access Management

| Method   | Endpoint              | Description                               | Allowed Roles              |
| :------- | :-------------------- | :---------------------------------------- | :------------------------- |
| `GET`    | `/roles`              | Lists the system's role catalog           | `admin, auditor, operator` |
| `GET`    | `/users`              | Obtains the directory and logical state   | `admin, auditor, operator` |
| `POST`   | `/users`              | Hashes credentials and registers a user   | `admin`                    |
| `DELETE` | `/users/{id}`         | Executes a logical deletion (Soft Delete) | `admin`                    |
| `POST`   | `/users/{id}/restore` | Reverts the logical deletion              | `admin`                    |

### 📜 Log and Traffic

| Method | Endpoint         | Description                             | Allowed Roles    |
| :----- | :--------------- | :-------------------------------------- | :--------------- |
| `GET`  | `/audit-logs`    | Returns the 50 most recent events       | `admin, auditor` |
| `POST` | `/demo/simulate` | Injects simulated chronological traffic | `admin`          |

```
```