# Authentication API Testing Guide

This document provides instructions for testing the authentication system using Postman, including examples of API calls and how to use the authentication tokens with protected endpoints.

## Prerequisites

1. Ensure you've run database migrations and seeders:
```bash
php artisan migrate
php artisan db:seed
```

2. The system has created two test users:
   - Admin User: `admin@example.com` / `Admin123!`
   - Regular User: `user@example.com` (password was auto-generated)

## Postman Collection Setup

1. Create a new Postman Collection called "Person Management API"
2. Set up environment variables:
   - `base_url`: Your API base URL (e.g., `http://localhost:8000/api`)
   - `admin_token`: Will store the admin authentication token
   - `user_token`: Will store the regular user authentication token

## Test Scenarios

### 1. Authentication Flow

#### 1.1 Admin Login

**Request:**
- Method: `POST`
- URL: `{{base_url}}/login`
- Headers:
  - Content-Type: `application/json`
  - Accept: `application/json`
- Body (raw JSON):
```json
{
    "email": "admin@example.com",
    "password": "Admin123!",
    "device_name": "postman"
}
```

**Postman Test Script:**
```javascript
// Parse response
var jsonData = pm.response.json();

// Test response structure
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response has correct structure", function () {
    pm.expect(jsonData.success).to.eql(true);
    pm.expect(jsonData.data).to.have.property('token');
    pm.expect(jsonData.data.user).to.have.property('is_admin');
    pm.expect(jsonData.data.user.is_admin).to.eql(true);
});

// Save token to environment variable
if (jsonData.data && jsonData.data.token) {
    pm.environment.set("admin_token", jsonData.data.token);
}
```

#### 1.2 Get Admin Profile

**Request:**
- Method: `GET`
- URL: `{{base_url}}/user`
- Headers:
  - Accept: `application/json`
  - Authorization: `Bearer {{admin_token}}`

**Postman Test Script:**
```javascript
var jsonData = pm.response.json();

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("User is admin", function () {
    pm.expect(jsonData.data.user.is_admin).to.eql(true);
});
```

#### 1.3 Register a New User (Admin Only)

**Request:**
- Method: `POST`
- URL: `{{base_url}}/register`
- Headers:
  - Content-Type: `application/json`
  - Accept: `application/json`
  - Authorization: `Bearer {{admin_token}}`
- Body (raw JSON):
```json
{
    "name": "New Test User",
    "email": "newuser@example.com",
    "password": "Password123!",
    "is_admin": false
}
```

**Postman Test Script:**
```javascript
var jsonData = pm.response.json();

pm.test("Status code is 201", function () {
    pm.response.to.have.status(201);
});

pm.test("User created successfully", function () {
    pm.expect(jsonData.success).to.eql(true);
    pm.expect(jsonData.message).to.eql("User created successfully");
});
```

#### 1.4 Login as New User

**Request:**
- Method: `POST`
- URL: `{{base_url}}/login`
- Headers:
  - Content-Type: `application/json`
  - Accept: `application/json`
- Body (raw JSON):
```json
{
    "email": "newuser@example.com",
    "password": "Password123!",
    "device_name": "postman"
}
```

**Postman Test Script:**
```javascript
var jsonData = pm.response.json();

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

// Save token to environment variable
if (jsonData.data && jsonData.data.token) {
    pm.environment.set("user_token", jsonData.data.token);
}
```

#### 1.5 Regular User Cannot Register New Users

**Request:**
- Method: `POST`
- URL: `{{base_url}}/register`
- Headers:
  - Content-Type: `application/json`
  - Accept: `application/json`
  - Authorization: `Bearer {{user_token}}`
- Body (raw JSON):
```json
{
    "name": "Another User",
    "email": "another@example.com",
    "password": "Password123!",
    "is_admin": false
}
```

**Postman Test Script:**
```javascript
pm.test("Status code is 403 (Forbidden)", function () {
    pm.response.to.have.status(403);
});
```

#### 1.6 Logout Admin

**Request:**
- Method: `POST`
- URL: `{{base_url}}/logout`
- Headers:
  - Accept: `application/json`
  - Authorization: `Bearer {{admin_token}}`

**Postman Test Script:**
```javascript
var jsonData = pm.response.json();

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Logged out successfully", function () {
    pm.expect(jsonData.success).to.eql(true);
    pm.expect(jsonData.message).to.eql("Logged out successfully");
});

// Clear token from environment
pm.environment.unset("admin_token");
```

### 2. Accessing Protected API Endpoints

#### 2.1 Trying to Access Protected Endpoint Without Token

**Request:**
- Method: `GET`
- URL: `{{base_url}}/persons`
- Headers:
  - Accept: `application/json`

**Postman Test Script:**
```javascript
pm.test("Status code is 401 (Unauthorized)", function () {
    pm.response.to.have.status(401);
});
```

#### 2.2 Accessing Protected Endpoint With Token

**Request:**
- Method: `GET`
- URL: `{{base_url}}/persons`
- Headers:
  - Accept: `application/json`
  - Authorization: `Bearer {{user_token}}`

**Postman Test Script:**
```javascript
var jsonData = pm.response.json();

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response has correct structure", function () {
    pm.expect(jsonData.success).to.eql(true);
    pm.expect(jsonData).to.have.property('data');
});
```

## Automated Testing Sequence

To create an automated test sequence in Postman:

1. Create a folder for "Authentication Tests" in your collection
2. Add all the test requests above to this folder
3. Right-click on the folder and select "Run"
4. In the Collection Runner, deselect any requests you don't want to run
5. Click "Run" to execute the tests in sequence

## Using PostmanTestAPI.json Collection

A complete Postman collection has been provided in this repository. To use it:

1. In Postman, click on "Import"
2. Upload or paste the contents of `PostmanTestAPI.json`
3. Create an environment with the variable `base_url` set to your API URL
4. Run the collection

## Automated Test Script

You can also run the tests using Newman (Postman's command-line runner):

```bash
# Install Newman
npm install -g newman

# Run the collection
newman run PostmanTestAPI.json -e environment.json
```

## Security Best Practices Implemented

1. **Token-based Authentication**: Using Laravel Sanctum for secure API tokens
2. **Password Hashing**: All passwords are hashed using bcrypt
3. **Role-based Access Control**: Admin-specific endpoints protected
4. **Token Abilities**: Tokens are created with specific abilities based on user role
5. **Token Revocation**: Tokens can be revoked on logout
6. **Request Validation**: All inputs are validated before processing