# Employee Patrol Login API

## Overview

Authenticates an employee for the mobile app and issues a Laravel Sanctum token.
Unlike the standard employee login endpoint, this endpoint only grants access
when the employee has a current active assignment to an active service.

## Endpoint

```http
POST /api/v1/employee/auth/patrol-login
Content-Type: application/json
Accept: application/json
```

Authentication is not required to call this endpoint. Use the returned token as
a bearer token for protected employee endpoints:

```http
Authorization: Bearer <token>
```

## Request body

Send a JSON object with:

| Field | Type | Required | Description |
|---|---|---:|---|
| `login` | string | One identifier is required | Employee email, phone number, or employee code. |
| `email` | string | Fallback | Accepted as a legacy alternative when `login` is omitted. |
| `phone` | string | Fallback | Accepted as a legacy alternative when `login` and `email` are omitted. |
| `password` | string | Yes | Password; at least 6 characters. |

The identifier precedence is `login`, then `email`, then `phone`. When using
`email` or `phone`, submit only one identifier field. Whitespace around the
selected identifier is trimmed.

### Example

```bash
curl -X POST "http://localhost:8000/api/v1/employee/auth/patrol-login" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "login": "guard@example.com",
    "password": "your-password"
  }'
```

The identifier can also be an employee phone number or employee code.

## Successful response

**HTTP 200**

```json
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 42,
      "first_name": "Alex",
      "last_name": "Guard",
      "email": "guard@example.com",
      "phone": "+60123456789",
      "avatar": null,
      "employee_id": "EMP0042",
      "employee_code": "EMP0042",
      "join_date": "2024-01-15",
      "last_login_at": "2026-10-21T04:30:00.000000Z",
      "source": "internal",
      "geofencing_enabled": false,
      "profile": {
        "employee_id": "EMP0042",
        "employee_code": "EMP0042",
        "phone": "+60123456789",
        "alternate_phone": null,
        "address": null,
        "city": null,
        "country": null,
        "postal_code": null,
        "date_of_birth": null,
        "gender": null,
        "emergency_contact": null,
        "blood_group": null,
        "marital_status": null,
        "nationality": null,
        "join_date": "2024-01-15"
      },
      "departments": [],
      "designations": [],
      "roles": []
    },
    "token": "<sanctum-token>",
    "token_type": "Bearer"
  }
}
```

The user fields and profile values reflect the employee record; nullable fields
may be `null`, and relationship arrays may be empty. `source` indicates the
authentication source (`internal` or `external`). Token expiry is controlled by
the application's Sanctum configuration.

## Error responses

### Validation failed

**HTTP 422** — the identifier is missing, or the password is missing or shorter
than 6 characters.

```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "login": [
      "The login (email, phone, or employee code) field is required."
    ]
  }
}
```

The `errors` object contains the fields that failed validation.

### Invalid credentials

**HTTP 401** — the identifier could not be authenticated or the password is
incorrect.

```json
{
  "success": false,
  "message": "The provided credentials are incorrect."
}
```

### Patrol Setup required

**HTTP 403** — credentials are valid, but the employee does not have a current,
active assignment to an active service.

```json
{
  "success": false,
  "message": "Please complete the Patrol Setup before logging in."
}
```

### Inactive account

**HTTP 403**

```json
{
  "success": false,
  "message": "Your account is not active. Please contact administrator."
}
```

### Server error

**HTTP 500** — an unexpected login or token-generation error occurred. The
response includes a `message` and may include an `error` detail; clients should
not rely on that detail.

## Notes

- This route is intended for mobile login requiring completed Patrol Setup.
- The standard `POST /api/v1/employee/auth/login` route remains available and
  does not apply this Patrol Setup gate.
- Store the returned token securely and send it as a bearer token on subsequent
  authenticated API calls.

For the break-details, break-start, and break-end API reference, including
request fields, responses, and error cases, see
[Employee_Attendance_Break_API.md](./Employee_Attendance_Break_API.md).