# Roles & Permissions API Documentation

## Overview

This document provides a comprehensive guide for implementing the Roles and Permissions management system in the admin dashboard. The system uses **Spatie Laravel Permission** package to manage roles and permissions.

**Base URL:** `{{APP_URL}}/api/v1/role`

**Authentication:** All endpoints require a valid **Sanctum Bearer token**.

---

## Table of Contents

1. [Core Concepts](#1-core-concepts)
2. [Role Management](#2-role-management)
3. [Permission Management](#3-permission-management)
4. [Assigning Roles to Users](#4-assigning-roles-to-users)
5. [Assigning Permissions to Roles](#5-assigning-permissions-to-roles)
6. [Revoking Permissions from Roles](#6-revoking-permissions-from-roles)
7. [Predefined Roles & Permissions](#7-predefined-roles--permissions)
8. [Complete API Endpoint Summary](#8-complete-api-endpoint-summary)
9. [Frontend Implementation Guide](#9-frontend-implementation-guide)

---

## 1. Core Concepts

### Roles

Roles are collections of permissions. A user can have one or multiple roles assigned. The system has three predefined roles:

| Role       | Slug       | Description                                                      |
|------------|------------|------------------------------------------------------------------|
| **Admin**  | `admin`    | Full system access with all permissions                          |
| **User**   | `user`     | Default role for newly registered users (basic navigation only)  |
| **Customer**| `customer`| Role assigned after completing profile (can perform transactions) |

### Permissions

Permissions are granular access controls. They define specific actions a user can perform. The system has 11 predefined permissions:

| Permission             | Slug                     | Description                                    |
|------------------------|--------------------------|------------------------------------------------|
| Navigate Application   | `navigate_application`   | Basic app navigation                           |
| Perform Transactions   | `perform_transactions`   | Execute transactions                           |
| Manage Users           | `manage_users`           | View, edit, delete users                       |
| Manage Roles           | `manage_roles`           | Create, edit, delete roles                     |
| Manage Permissions     | `manage_permissions`     | Create, edit, delete permissions               |
| Manage Customers       | `manage_customers`       | Manage customer accounts                       |
| Manage Transactions    | `manage_transactions`    | View and manage all transactions               |
| View Ledger            | `view_ledger`            | View ledger entries                            |
| Manage Ledger          | `manage_ledger`          | Create and edit ledger entries                 |
| Approve Ledger         | `approve_ledger`         | Approve ledger entries                         |
| View Reports           | `view_reports`           | Access and view reports                        |

### Default Permission Assignment by Role

| Permission                | Admin | User | Customer |
|---------------------------|:-----:|:----:|:--------:|
| `navigate_application`    | ✅    | ✅   | ✅       |
| `perform_transactions`    | ✅    | ❌   | ✅       |
| `manage_users`            | ✅    | ❌   | ❌       |
| `manage_roles`            | ✅    | ❌   | ❌       |
| `manage_permissions`      | ✅    | ❌   | ❌       |
| `manage_customers`        | ✅    | ❌   | ❌       |
| `manage_transactions`     | ✅    | ❌   | ❌       |
| `view_ledger`             | ✅    | ❌   | ❌       |
| `manage_ledger`           | ✅    | ❌   | ❌       |
| `approve_ledger`          | ✅    | ❌   | ❌       |
| `view_reports`            | ✅    | ❌   | ❌       |

---

## 2. Role Management

### 2.1 List All Roles

Get all roles with their associated permissions.

```http
GET /api/v1/role/roles
```

#### Response `200 OK`

```json
{
    "success": true,
    "message": "Roles retrieved successfully",
    "data": {
        "roles": [
            {
                "id": 1,
                "name": "admin",
                "guard_name": "api",
                "permissions": [
                    "manage_customers",
                    "perform_transactions",
                    "manage_users",
                    "manage_roles",
                    "manage_permissions",
                    "manage_transactions",
                    "navigate_application",
                    "view_ledger",
                    "manage_ledger",
                    "approve_ledger",
                    "view_reports"
                ],
                "created_at": "2026-06-24 18:55:30",
                "updated_at": "2026-06-24 18:55:30"
            },
            {
                "id": 2,
                "name": "user",
                "guard_name": "api",
                "permissions": [
                    "navigate_application"
                ],
                "created_at": "2026-06-24 18:55:30",
                "updated_at": "2026-06-24 18:55:30"
            },
            {
                "id": 3,
                "name": "customer",
                "guard_name": "api",
                "permissions": [
                    "perform_transactions",
                    "navigate_application"
                ],
                "created_at": "2026-06-24 18:55:30",
                "updated_at": "2026-06-24 18:55:30"
            }
        ]
    }
}
```

---

### 2.2 Create a New Role

```http
POST /api/v1/role/roles
```

#### Request Body

```json
{
    "name": "manager",
    "guard_name": "api",
    "permissions": ["manage_users", "manage_customers", "view_reports"]
}
```

| Field         | Type   | Required | Default  | Description                               |
|---------------|--------|----------|----------|-------------------------------------------|
| `name`        | string | **Yes**  | —        | Unique role name                          |
| `guard_name`  | string | No       | `api`    | Authentication guard                      |
| `permissions` | array  | No       | `[]`     | Array of permission names to assign       |

#### Response `201 Created`

```json
{
    "success": true,
    "message": "Role created successfully",
    "data": {
        "role": {
            "id": 4,
            "name": "manager",
            "guard_name": "api",
            "permissions": ["manage_users", "manage_customers", "view_reports"],
            "created_at": "2026-07-09 14:30:00"
        }
    }
}
```

#### Response `422 Validation Error`

```json
{
    "success": false,
    "message": "The name has already been taken.",
    "data": {
        "name": ["The name has already been taken."]
    },
    "code": 422
}
```

---

### 2.3 Update a Role

```http
PUT /api/v1/role/roles/{id}
```

#### Request Body

```json
{
    "name": "senior-manager",
    "permissions": ["manage_users", "manage_customers", "view_reports", "manage_transactions"]
}
```

| Field         | Type   | Required | Description                               |
|---------------|--------|----------|-------------------------------------------|
| `name`        | string | **Yes**  | Role name (must be unique)                |
| `permissions` | array  | No       | Array of permission names (replaces all)  |

#### Response `200 OK`

```json
{
    "success": true,
    "message": "Role updated successfully",
    "data": {
        "role": {
            "id": 4,
            "name": "senior-manager",
            "guard_name": "api",
            "permissions": ["manage_users", "manage_customers", "view_reports", "manage_transactions"],
            "updated_at": "2026-07-09 15:00:00"
        }
    }
}
```

---

### 2.4 Delete a Role

```http
DELETE /api/v1/role/roles/{id}
```

#### Response `200 OK`

```json
{
    "success": true,
    "message": "Role deleted successfully",
    "data": []
}
```

#### Response `403 Forbidden` (Protected Role)

```json
{
    "success": false,
    "message": "Cannot delete protected role: admin",
    "code": 403
}
```

> **Note:** The `admin` role is protected and cannot be deleted.

---

## 3. Permission Management

### 3.1 List All Permissions

```http
GET /api/v1/role/permissions
```

#### Response `200 OK`

```json
{
    "success": true,
    "message": "Permissions retrieved successfully",
    "data": {
        "permissions": [
            {
                "id": 1,
                "name": "manage_users",
                "guard_name": "api",
                "created_at": "2026-06-24 18:55:30",
                "updated_at": "2026-06-24 18:55:30"
            },
            {
                "id": 2,
                "name": "manage_roles",
                "guard_name": "api",
                "created_at": "2026-06-24 18:55:30",
                "updated_at": "2026-06-24 18:55:30"
            }
        ]
    }
}
```

---

### 3.2 Create a New Permission

```http
POST /api/v1/role/permissions
```

#### Request Body

```json
{
    "name": "export_reports",
    "guard_name": "api"
}
```

| Field         | Type   | Required | Default  | Description                  |
|---------------|--------|----------|----------|------------------------------|
| `name`        | string | **Yes**  | —        | Unique permission name       |
| `guard_name`  | string | No       | `api`    | Authentication guard         |

#### Response `201 Created`

```json
{
    "success": true,
    "message": "Permission created successfully",
    "data": {
        "permission": {
            "id": 12,
            "name": "export_reports",
            "guard_name": "api",
            "created_at": "2026-07-09 14:30:00"
        }
    }
}
```

---

### 3.3 Update a Permission

```http
PUT /api/v1/role/permissions/{id}
```

#### Request Body

```json
{
    "name": "export_all_reports"
}
```

#### Response `200 OK`

```json
{
    "success": true,
    "message": "Permission updated successfully",
    "data": {
        "permission": {
            "id": 12,
            "name": "export_all_reports",
            "guard_name": "api",
            "updated_at": "2026-07-09 15:00:00"
        }
    }
}
```

---

### 3.4 Delete a Permission

```http
DELETE /api/v1/role/permissions/{id}
```

#### Response `200 OK`

```json
{
    "success": true,
    "message": "Permission deleted successfully",
    "data": []
}
```

---

## 4. Assigning Roles to Users

Assign a role to a specific user.

```http
POST /api/v1/role/assign/role
```

#### Request Body

```json
{
    "user_id": 1,
    "role": "customer"
}
```

| Field     | Type   | Required | Description                   |
|-----------|--------|----------|-------------------------------|
| `user_id` | int    | **Yes**  | ID of the user                |
| `role`    | string | **Yes**  | Name of the role to assign    |

#### Response `200 OK`

```json
{
    "success": true,
    "message": "Role assigned to user successfully",
    "data": {
        "user": {
            "id": 1,
            "name": "John Doe",
            "email": "john@example.com",
            "roles": ["customer"],
            "permissions": ["perform_transactions", "navigate_application"]
        }
    }
}
```

> **Note:** A user can have multiple roles. Use `syncRoles` in the admin update endpoint to replace all roles at once, or `assignRole` to add a role without removing existing ones.

---

## 5. Assigning Permissions to Roles

Grant a permission to a specific role.

```http
POST /api/v1/role/role/permission
```

#### Request Body

```json
{
    "role": "customer",
    "permission": "view_reports"
}
```

| Field        | Type   | Required | Description                       |
|--------------|--------|----------|-----------------------------------|
| `role`       | string | **Yes**  | Name of the role                  |
| `permission` | string | **Yes**  | Name of the permission to grant   |

#### Response `200 OK`

```json
{
    "success": true,
    "message": "Permission assigned to role successfully",
    "data": {
        "role": "customer",
        "permissions": ["perform_transactions", "navigate_application", "view_reports"]
    }
}
```

---

## 6. Revoking Permissions from Roles

Remove a permission from a specific role.

```http
POST /api/v1/role/role/permission/revoke
```

#### Request Body

```json
{
    "role": "customer",
    "permission": "view_reports"
}
```

| Field        | Type   | Required | Description                       |
|--------------|--------|----------|-----------------------------------|
| `role`       | string | **Yes**  | Name of the role                  |
| `permission` | string | **Yes**  | Name of the permission to revoke  |

#### Response `200 OK`

```json
{
    "success": true,
    "message": "Permission revoked from role successfully",
    "data": {
        "role": "customer",
        "permissions": ["perform_transactions", "navigate_application"]
    }
}
```

---

## 7. Predefined Roles & Permissions

These values are defined in the backend enums and seeded via [`RolePermissionSeeder`](database/seeders/RolePermissionSeeder.php).

### Permissions Enum (`App\Enum\PermissionsEnum`)

```php
enum PermissionsEnum: string
{
    case ManageUsers = 'manage_users';
    case ManageRoles = 'manage_roles';
    case ManagePermissions = 'manage_permissions';
    case ManageCustomers = 'manage_customers';
    case ManageTransactions = 'manage_transactions';
    case PerformTransactions = 'perform_transactions';
    case NavigateApplication = 'navigate_application';
    case ViewLedger = 'view_ledger';
    case ManageLedger = 'manage_ledger';
    case ApproveLedger = 'approve_ledger';
    case ViewReports = 'view_reports';
}
```

### Roles Enum (`App\Enum\RolesEnum`)

```php
enum RolesEnum: string
{
    case Admin = 'admin';
    case User = 'user';
    case Customer = 'customer';
}
```

---

## 8. Complete API Endpoint Summary

| Method   | Endpoint                                    | Description                       | Auth Required |
|----------|---------------------------------------------|-----------------------------------|---------------|
| `GET`    | `/api/v1/role/roles`                        | List all roles with permissions   | Sanctum Token |
| `POST`   | `/api/v1/role/roles`                        | Create a new role                 | Sanctum Token |
| `PUT`    | `/api/v1/role/roles/{id}`                   | Update a role                     | Sanctum Token |
| `DELETE` | `/api/v1/role/roles/{id}`                   | Delete a role                     | Sanctum Token |
| `GET`    | `/api/v1/role/permissions`                  | List all permissions              | Sanctum Token |
| `POST`   | `/api/v1/role/permissions`                  | Create a new permission           | Sanctum Token |
| `PUT`    | `/api/v1/role/permissions/{id}`             | Update a permission               | Sanctum Token |
| `DELETE` | `/api/v1/role/permissions/{id}`             | Delete a permission               | Sanctum Token |
| `POST`   | `/api/v1/role/assign/role`                  | Assign role to user               | Sanctum Token |
| `POST`   | `/api/v1/role/role/permission`              | Assign permission to role         | Sanctum Token |
| `POST`   | `/api/v1/role/role/permission/revoke`       | Revoke permission from role       | Sanctum Token |

---

## 9. Frontend Implementation Guide

### 9.1 Getting Authenticated User's Roles & Permissions

When a user logs in or their token is verified, the response includes their roles and permissions:

**Login Response** (`POST /api/v1/auth/login`):

```json
{
    "success": true,
    "message": "Login successful",
    "data": {
        "token": "1|sanctum_token_here...",
        "user": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john@example.com",
            "roles": ["admin"],
            "permissions": [
                "manage_users",
                "manage_roles",
                "manage_permissions",
                "navigate_application",
                "view_reports"
            ],
            "referral": {
                "code": "ABC123",
                "link": "https://yourapp.com/register?ref=ABC123",
                "total_referrals": 5
            }
        }
    }
}
```

**Verify Token Response** (`GET /api/v1/auth/verify`):

```json
{
    "success": true,
    "data": {
        "valid": true,
        "user": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john@example.com",
            "roles": ["admin"],
            "permissions": ["manage_users", "manage_roles", "manage_permissions", "navigate_application", "view_reports"]
        }
    },
    "message": "Token is valid"
}
```

### 9.2 Frontend Permission Check Utilities

```typescript
// Types based on backend enums
type PermissionSlug =
    | 'manage_users'
    | 'manage_roles'
    | 'manage_permissions'
    | 'manage_customers'
    | 'manage_transactions'
    | 'perform_transactions'
    | 'navigate_application'
    | 'view_ledger'
    | 'manage_ledger'
    | 'approve_ledger'
    | 'view_reports';

type RoleSlug = 'admin' | 'user' | 'customer';

// Permission checking utilities
interface AuthUser {
    id: number;
    first_name: string;
    last_name: string;
    email: string;
    roles: string[];
    permissions: string[];
}

class PermissionGuard {
    private user: AuthUser | null = null;

    constructor(user: AuthUser | null) {
        this.user = user;
    }

    hasPermission(permission: PermissionSlug): boolean {
        if (!this.user) return false;
        return this.user.permissions.includes(permission);
    }

    hasRole(role: RoleSlug): boolean {
        if (!this.user) return false;
        return this.user.roles.includes(role);
    }

    hasAnyRole(roles: RoleSlug[]): boolean {
        if (!this.user) return false;
        return roles.some(role => this.user!.roles.includes(role));
    }

    hasAllPermissions(permissions: PermissionSlug[]): boolean {
        if (!this.user) return false;
        return permissions.every(p => this.user!.permissions.includes(p));
    }

    isAdmin(): boolean {
        return this.hasRole('admin');
    }
}

// Usage in React component
const AdminDashboard: React.FC = () => {
    const { user } = useAuth(); // Your auth context/hook
    const guard = new PermissionGuard(user);

    if (!guard.isAdmin()) {
        return <AccessDenied />;
    }

    return (
        <div>
            {guard.hasPermission('manage_users') && <UserManagementPanel />}
            {guard.hasPermission('manage_roles') && <RoleManagementPanel />}
            {guard.hasPermission('view_reports') && <ReportsPanel />}
        </div>
    );
};
```

### 9.3 UI Component Guidance

#### Roles Management Page

- **Roles List:** Display roles in a table with columns: Role Name, Guard, Permissions (as badges/tags), Created Date, Actions
- **Create Role:** Modal or slide-out form with fields: Role Name (text input), Permissions (multi-select checkboxes from permissions list)
- **Edit Role:** Click a role to open edit modal, showing current name and assigned permissions (checkboxes)
- **Delete Role:** Confirmation dialog. Disable delete for `admin` role

#### Permissions Management Page

- **Permissions List:** Display permissions in a table with: Name, Guard, Created Date, Actions
- **Create Permission:** Modal with just a name text input
- **Edit Permission:** Modal to rename
- **Delete Permission:** Confirmation dialog

#### Role Assignment (in User Edit Page)

- When editing a user in the admin panel, show a multi-select dropdown of all available roles
- On save, send the selected roles array to `PUT /api/v1/admin/users/{id}`

#### User Role Badges

- Display user roles as colored badges in the users table
- Admin: Red/Danger badge
- Customer: Green/Success badge
- User: Blue/Primary badge

### 9.4 Roles & Permissions Frontend Flow

```
User Logs In
    ↓
Auth API returns { user: { roles: [...], permissions: [...] } }
    ↓
Store in AuthContext / Redux / Zustand
    ↓
Route Guards / Component Guards check permissions
    ↓
Show/Hide UI elements based on permissions

Example Routes:
/admin/* → Guard: isAdmin() OR hasPermission('manage_users')
/admin/users → Guard: hasPermission('manage_users')
/admin/roles → Guard: hasPermission('manage_roles')
/admin/permissions → Guard: hasPermission('manage_permissions')
/admin/reports → Guard: hasPermission('view_reports')
/admin/transactions → Guard: hasPermission('manage_transactions')
```

### 9.5 Implementation Checklist

- [ ] On login/auth-verify, store `roles` and `permissions` in client-side state
- [ ] Create a `PermissionGuard` utility class or hook for permission checks
- [ ] Implement route-level guards that redirect to "Access Denied" page
- [ ] Implement component-level guards that hide UI elements conditionally
- [ ] **Roles Page:** Table listing all roles with their permissions
- [ ] **Roles Page:** Create/Edit role modal with permission checkboxes
- [ ] **Roles Page:** Delete role with confirmation (disable for `admin`)
- [ ] **Permissions Page:** Table listing all permissions
- [ ] **Permissions Page:** Create/Edit permission modal
- [ ] **Permissions Page:** Delete permission with confirmation
- [ ] **User Edit:** Role assignment multi-select
- [ ] **Users Table:** Role badges/colored tags for each user
- [ ] **Dashboard:** Show role distribution stats

---

## Data Types Reference

```typescript
interface Role {
    id: number;
    name: string;
    guard_name: string;
    permissions: string[];
    created_at: string;
    updated_at: string;
}

interface Permission {
    id: number;
    name: string;
    guard_name: string;
    created_at: string;
    updated_at: string;
}

interface AssignRoleRequest {
    user_id: number;
    role: string;
}

interface AssignPermissionRequest {
    role: string;
    permission: string;
}

interface StoreRoleRequest {
    name: string;
    guard_name?: string;
    permissions?: string[];
}

interface StorePermissionRequest {
    name: string;
    guard_name?: string;
}

interface ApiResponse<T> {
    success: boolean;
    message: string;
    data: T;
    code?: number;
}
```