# Admin User Management API Documentation

## Overview

This document provides a comprehensive guide for implementing the Admin User Management dashboard. The admin panel allows administrators to **view, search, filter, update, activate/deactivate, and delete** user accounts.

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

**Authentication:** All admin endpoints require a valid **Sanctum Bearer token** with admin role/permissions.

**Authorization:** The requesting user must have the `manage_users` permission or the `admin` role assigned.

---

## Table of Contents

1. [Headers & Authentication](#1-headers--authentication)
2. [Dashboard Statistics](#2-dashboard-statistics)
3. [List All Users](#3-list-all-users)
4. [Get Single User](#4-get-single-user)
5. [Update User (Admin)](#5-update-user-admin)
6. [Delete User (Soft Delete)](#6-delete-user-soft-delete)
7. [Permanently Delete User](#7-permanently-delete-user)
8. [Restore User](#8-restore-user)
9. [Toggle User Active Status](#9-toggle-user-active-status)
10. [Get User Login History](#10-get-user-login-history)

---

## 1. Headers & Authentication

All requests must include:

```http
Authorization: Bearer <sanctum_token>
Accept: application/json
Content-Type: application/json
```

---

## 2. Dashboard Statistics

Get aggregate user statistics for the admin dashboard overview.

### Request

```http
GET /api/v1/admin/stats
```

### Response `200 OK`

```json
{
    "success": true,
    "message": "Dashboard stats retrieved successfully",
    "data": {
        "stats": {
            "user_overview": {
                "total_users": 1250,
                "active_users": 1100,
                "verified_users": 980,
                "unverified_users": 270,
                "phone_verified_users": 850,
                "deleted_users": 45,
                "users_with_complete_profile": 750,
                "user_completion_rate": 60.0
            },
            "registration_trend": {
                "daily_30_days": [
                    { "date": "2026-06-09", "count": 5 },
                    { "date": "2026-06-10", "count": 12 }
                ],
                "monthly_6_months": [
                    { "month": "2026-01", "count": 120 },
                    { "month": "2026-02", "count": 145 }
                ],
                "today": 2,
                "this_week": 18,
                "this_month": 65,
                "last_7_days": 32
            },
            "role_distribution": {
                "admin": 5,
                "user": 800,
                "customer": 445
            },
            "login_analytics": {
                "total_logins": 3450,
                "today": 28,
                "this_week": 145,
                "this_month": 520,
                "by_channel": {
                    "mobile": 2100,
                    "web": 850,
                    "api": 380,
                    "postman": 120
                },
                "trend_14_days": [
                    { "date": "2026-06-25", "count": 45 },
                    { "date": "2026-06-26", "count": 52 }
                ]
            },
            "active_users_metrics": {
                "daily_active_users": 22,
                "weekly_active_users": 110,
                "monthly_active_users": 380
            },
            "referral_analytics": {
                "total_referral_links": 850,
                "users_with_referral_links": 800,
                "total_referrals": 320,
                "referral_conversion_rate": 25.6,
                "average_referrals_per_referrer": 0.4,
                "today": 2,
                "this_week": 15,
                "this_month": 48,
                "trend_30_days": [
                    { "date": "2026-06-09", "count": 3 },
                    { "date": "2026-06-10", "count": 7 }
                ],
                "monthly_6_months": [
                    { "month": "2026-01", "count": 45 },
                    { "month": "2026-02", "count": 52 }
                ],
                "top_referrers": [
                    {
                        "user_id": 1,
                        "name": "Jane Smith",
                        "email": "jane@example.com",
                        "total_referrals": 24
                    }
                ]
            },
            "notification_analytics": {
                "total_notifications": 5200,
                "unread_notifications": 1200,
                "by_type": {
                    "transaction": 2800,
                    "system": 1200,
                    "promotion": 600,
                    "update": 400,
                    "alert": 200
                },
                "by_priority": {
                    "normal": 3500,
                    "high": 1200,
                    "low": 500
                },
                "trend_14_days": [
                    { "date": "2026-06-25", "count": 85 },
                    { "date": "2026-06-26", "count": 92 }
                ]
            },
            "verification_funnel": {
                "registered": 1250,
                "email_verified": 980,
                "phone_verified": 850,
                "profile_completed": 750
            },
            "verification_breakdown": {
                "both_verified": 780,
                "only_email_verified": 200,
                "only_phone_verified": 70,
                "neither_verified": 200
            }
        }
    }
}
```

---

## 3. List All Users

Get a paginated, searchable, filterable list of all users.

### Request

```http
GET /api/v1/admin/users?page=1&per_page=20&search=john&role=user&status=active&is_verified=verified&sort_by=created_at&sort_order=desc
```

### Query Parameters

| Parameter    | Type   | Required | Default | Description                                                    |
|-------------|--------|----------|---------|----------------------------------------------------------------|
| `page`       | int    | No       | `1`     | Page number for pagination                                     |
| `per_page`   | int    | No       | `20`    | Items per page (max: 100)                                      |
| `search`     | string | No       | `null`  | Search by name, email, or phone number                         |
| `role`       | string | No       | `null`  | Filter by role name: `admin`, `user`, `customer`                |
| `status`     | string | No       | `null`  | Filter by status: `active`, `inactive`, `deleted`               |
| `is_verified`| string | No       | `null`  | Filter by verification: `verified`, `unverified`                |
| `sort_by`    | string | No       | `created_at` | Sort field: `created_at`, `first_name`, `last_name`, `email`, `updated_at` |
| `sort_order` | string | No       | `desc`  | Sort direction: `asc`, `desc`                                  |

### Response `200 OK`

```json
{
    "success": true,
    "message": "Users retrieved successfully",
    "data": {
        "users": [
            {
                "id": 1,
                "first_name": "John",
                "last_name": "Doe",
                "email": "john@example.com",
                "phone_number": "08123456789",
                "is_active": true,
                "is_verified": true,
                "email_verified_at": "2026-07-01 10:30:00",
                "phone_verified_at": "2026-07-01 10:35:00",
                "roles": ["user"],
                "permissions": ["navigate_application"],
                "profile_photo_url": null,
                "is_profile_complete": false,
                "created_at": "2026-07-01 10:30:00",
                "updated_at": "2026-07-05 14:20:00",
                "deleted_at": null
            }
        ],
        "pagination": {
            "current_page": 1,
            "per_page": 20,
            "total": 1250,
            "last_page": 63,
            "from": 1,
            "to": 20
        }
    }
}
```

### Frontend Usage Example

```javascript
// Example: Fetch users with filters
const fetchUsers = async (params = {}) => {
    const queryParams = new URLSearchParams({
        page: params.page || 1,
        per_page: params.perPage || 20,
        ...(params.search && { search: params.search }),
        ...(params.role && { role: params.role }),
        ...(params.status && { status: params.status }),
        ...(params.isVerified && { is_verified: params.isVerified }),
        ...(params.sortBy && { sort_by: params.sortBy }),
        ...(params.sortOrder && { sort_order: params.sortOrder }),
    });

    const response = await fetch(`/api/v1/admin/users?${queryParams}`, {
        headers: {
            'Authorization': `Bearer ${token}`,
            'Accept': 'application/json',
        }
    });

    return response.json();
};
```

---

## 4. Get Single User

Get detailed information about a specific user.

### Request

```http
GET /api/v1/admin/users/{id}
```

### Response `200 OK`

```json
{
    "success": true,
    "message": "User retrieved successfully",
    "data": {
        "user": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john@example.com",
            "phone_number": "08123456789",
            "is_active": true,
            "is_verified": true,
            "email_verified_at": "2026-07-01 10:30:00",
            "phone_verified_at": "2026-07-01 10:35:00",
            "dob": "1995-03-15",
            "gender": "male",
            "address": "123 Main Street, Lagos",
            "nin": "12345678901",
            "roles": ["user"],
            "permissions": ["navigate_application"],
            "profile_photo_url": null,
            "is_profile_complete": true,
            "referral": {
                "code": "ABC123",
                "link": "https://yourapp.com/register?ref=ABC123",
                "total_referrals": 5
            },
            "created_at": "2026-07-01 10:30:00",
            "updated_at": "2026-07-05 14:20:00",
            "deleted_at": null,
            "deletion_reason": null,
            "deletion_requested_at": null
        }
    }
}
```

### Response `404 Not Found`

```json
{
    "success": false,
    "message": "User not found",
    "code": 404
}
```

---

## 5. Update User (Admin)

Update user details, including roles assignment.

### Request

```http
PUT /api/v1/admin/users/{id}
```

### Request Body

```json
{
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "phone_number": "08198765432",
    "is_active": true,
    "roles": ["customer"],
    "profile_photo_url": "https://example.com/photos/john.jpg"
}
```

| Field             | Type    | Required | Description                                        |
|------------------|---------|----------|----------------------------------------------------|
| `first_name`      | string  | No       | User's first name                                  |
| `last_name`       | string  | No       | User's last name                                   |
| `email`           | string  | No       | User's email (must be unique)                      |
| `phone_number`    | string  | No       | User's phone number (must be unique)               |
| `is_active`       | boolean | No       | Account active status                              |
| `roles`           | array   | No       | Array of role names to assign (replaces all roles)  |
| `profile_photo_url` | string | No     | URL to user's profile photo                        |

### Response `200 OK`

```json
{
    "success": true,
    "message": "User updated successfully",
    "data": {
        "user": {
            "id": 1,
            "first_name": "John",
            "last_name": "Smith",
            "email": "john.smith@example.com",
            "phone_number": "08198765432",
            "is_active": true,
            "roles": ["customer"],
            "updated_at": "2026-07-09 14:30:00"
        }
    }
}
```

### Response `422 Validation Error`

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

---

## 6. Delete User (Soft Delete)

Soft delete a user account. The user data is preserved in the database but the user cannot log in.

### Request

```http
DELETE /api/v1/admin/users/{id}
```

### Response `200 OK`

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

### Response `403 Forbidden` (Cannot delete admin)

```json
{
    "success": false,
    "message": "Cannot delete admin users. Please remove the admin role first.",
    "code": 403
}
```

---

## 7. Permanently Delete User

Permanently remove a user from the database. **This action cannot be undone.**

### Request

```http
DELETE /api/v1/admin/users/{id}/force
```

### Response `200 OK`

```json
{
    "success": true,
    "message": "User permanently deleted",
    "data": []
}
```

---

## 8. Restore User

Restore a soft-deleted user account.

### Request

```http
POST /api/v1/admin/users/{id}/restore
```

### Response `200 OK`

```json
{
    "success": true,
    "message": "User restored successfully",
    "data": {
        "user": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john@example.com",
            "restored_at": "2026-07-09 15:00:00"
        }
    }
}
```

---

## 9. Toggle User Active Status

Activate or deactivate a user account. This prevents login when deactivated.

### Request

```http
POST /api/v1/admin/users/{id}/toggle-active
```

### Response `200 OK` (User Activated)

```json
{
    "success": true,
    "message": "User activated successfully",
    "data": {
        "user": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john@example.com",
            "is_active": true
        }
    }
}
```

### Response `200 OK` (User Deactivated)

```json
{
    "success": true,
    "message": "User deactivated successfully",
    "data": {
        "user": {
            "id": 1,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john@example.com",
            "is_active": false
        }
    }
}
```

---

## 10. Get User Login History

Retrieve the login history for a specific user.

### Request

```http
GET /api/v1/admin/users/{id}/login-history?page=1&per_page=20
```

### Query Parameters

| Parameter  | Type | Required | Default | Description                |
|-----------|------|----------|---------|----------------------------|
| `page`     | int  | No       | `1`     | Page number                |
| `per_page` | int  | No       | `20`    | Items per page (max: 100)  |

### Response `200 OK`

```json
{
    "success": true,
    "message": "Login history retrieved successfully",
    "data": {
        "user_id": 1,
        "login_history": [
            {
                "id": 1,
                "ip_address": "192.168.1.1",
                "channel": "mobile",
                "user_agent": "Mozilla/5.0...",
                "location": {
                    "latitude": "6.5243793",
                    "longitude": "3.3792057",
                    "accuracy": "20.00"
                },
                "logged_in_at": "2026-07-09 10:30:00"
            }
        ],
        "pagination": {
            "current_page": 1,
            "per_page": 20,
            "total": 45,
            "last_page": 3
        }
    }
}
```

---

## Complete API Endpoint Summary

| Method     | Endpoint                                         | Description                     | Auth Required |
|-----------|--------------------------------------------------|---------------------------------|---------------|
| `GET`     | `/api/v1/admin/stats`                            | Dashboard statistics            | Sanctum Token |
| `GET`     | `/api/v1/admin/users`                            | List all users (paginated)      | Sanctum Token |
| `GET`     | `/api/v1/admin/users/{id}`                       | Get single user details         | Sanctum Token |
| `PUT`     | `/api/v1/admin/users/{id}`                       | Update user (admin)             | Sanctum Token |
| `DELETE`  | `/api/v1/admin/users/{id}`                       | Soft delete user                | Sanctum Token |
| `DELETE`  | `/api/v1/admin/users/{id}/force`                 | Permanently delete user         | Sanctum Token |
| `POST`    | `/api/v1/admin/users/{id}/restore`               | Restore soft-deleted user       | Sanctum Token |
| `POST`    | `/api/v1/admin/users/{id}/toggle-active`         | Activate/deactivate user        | Sanctum Token |
| `GET`     | `/api/v1/admin/users/{id}/login-history`         | Get user login history          | Sanctum Token |

---

## Frontend Implementation Checklist

- [ ] **Stats Cards:** Display total users, active users, verified/unverified users, recent registrations (7 days), and role distribution
- [ ] **User List Table:** Show users in a table with columns for name, email, phone, roles, status, verification, and creation date
- [ ] **Search Bar:** Implement client-side search with debounce to query by name, email, or phone
- [ ] **Filters:** Dropdowns for role, account status, and verification status
- [ ] **Pagination:** Use the pagination metadata to implement page navigation
- [ ] **Sorting:** Clickable column headers that toggle sort order and update the query params
- [ ] **User Detail View:** Full user profile page or modal with all user fields
- [ ] **Edit User Form:** Form to update user details and assign roles (multi-select for roles)
- [ ] **Toggle Active Button:** With confirmation dialog before deactivating/activating
- [ ] **Delete User:** With soft delete option and confirmation dialog
- [ ] **Restore User:** Option to restore deleted users in a "Deleted Users" tab or filter
- [ ] **Login History:** Expandable section or separate page showing login timestamps, IPs, channels, and locations

---

## User Object Schema

```typescript
interface User {
    id: number;
    first_name: string;
    last_name: string;
    email: string;
    phone_number: string;
    is_active: boolean;
    is_verified: boolean;
    email_verified_at: string | null;
    phone_verified_at: string | null;
    dob: string | null;           // Date of birth (YYYY-MM-DD)
    gender: string | null;        // "male" | "female" | "other"
    address: string | null;
    nin: string | null;           // National Identification Number
    roles: string[];
    permissions: string[];
    profile_photo_url: string | null;
    is_profile_complete: boolean;
    referral: {
        code: string | null;
        link: string | null;
        total_referrals: number;
    };
    created_at: string;
    updated_at: string;
    deleted_at: string | null;
    deletion_reason: string | null;
    deletion_requested_at: string | null;
}

interface Pagination {
    current_page: number;
    per_page: number;
    total: number;
    last_page: number;
    from: number | null;
    to: number | null;
}

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