> ## Documentation Index
> Fetch the complete documentation index at: https://withkazi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate with LaraCopilot API

> Learn how to authenticate with the LaraCopilot REST API using session cookies, verify your session with /api/admin/me, and log out securely.

LaraCopilot uses server-side session authentication. When you post valid admin credentials to `POST /api/admin/login`, the server creates a session and returns a session cookie. You must include that cookie with every subsequent API request. There are no API keys or bearer tokens — the session cookie is the sole authentication mechanism.

## Endpoints

| Method | Path                | Description                              |
| ------ | ------------------- | ---------------------------------------- |
| `POST` | `/api/admin/login`  | Authenticate and start a session.        |
| `POST` | `/api/admin/logout` | Invalidate the current session.          |
| `GET`  | `/api/admin/me`     | Return the authenticated user's details. |

***

## POST /api/admin/login

Validates the provided credentials and opens an admin session.

### Request body

<ParamField body="email" type="string" required>
  The admin account email address. Must be a valid email format.
</ParamField>

<ParamField body="password" type="string" required>
  The admin account password.
</ParamField>

### Response fields

<ResponseField name="message" type="string">
  Human-readable status message. `"Login successful."` on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="name" type="string">
      The full name of the authenticated admin user.
    </ResponseField>

    <ResponseField name="email" type="string">
      The email address of the authenticated admin user.
    </ResponseField>

    <ResponseField name="role" type="string">
      The role assigned to the user. One of `admin`, `manager`, or `supervisor`.
    </ResponseField>
  </Expandable>
</ResponseField>

### Code example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-domain.com/api/admin/login \
    -H "Content-Type: application/json" \
    -c cookies.txt \
    -d '{
      "email": "admin@business.com",
      "password": "admin123"
    }'
  ```

  ```json Response — 200 OK theme={null}
  {
    "message": "Login successful.",
    "data": {
      "name": "Admin User",
      "email": "admin@business.com",
      "role": "admin"
    }
  }
  ```

  ```json Response — 422 Invalid credentials theme={null}
  {
    "message": "Invalid credentials."
  }
  ```
</CodeGroup>

***

## GET /api/admin/me

Returns the session's current authenticated user. Use this to confirm a session is still active or to retrieve the logged-in user's details without re-authenticating.

### Response fields

<ResponseField name="message" type="string">
  `"Authenticated user loaded."` when the session is valid.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="name" type="string">
      The full name stored in the current session.
    </ResponseField>

    <ResponseField name="email" type="string">
      The email address stored in the current session.
    </ResponseField>

    <ResponseField name="logged_in" type="boolean">
      Always `true` when this endpoint returns HTTP 200.
    </ResponseField>
  </Expandable>
</ResponseField>

### Code example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://your-domain.com/api/admin/me \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

  ```json Response — 200 OK theme={null}
  {
    "message": "Authenticated user loaded.",
    "data": {
      "name": "Admin User",
      "email": "admin@business.com",
      "logged_in": true
    }
  }
  ```

  ```json Response — 401 Unauthorized theme={null}
  {
    "message": "Unauthorized."
  }
  ```
</CodeGroup>

***

## POST /api/admin/logout

Clears the current admin session. After a successful logout, the session cookie is no longer valid and all protected endpoints will return HTTP 401 until you log in again.

### Code example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-domain.com/api/admin/logout \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

  ```json Response — 200 OK theme={null}
  {
    "message": "Logged out successfully."
  }
  ```
</CodeGroup>

***

## Error handling

| HTTP status | Condition                                                     | Message                  |
| ----------- | ------------------------------------------------------------- | ------------------------ |
| `422`       | Credentials did not match any admin account.                  | `"Invalid credentials."` |
| `401`       | Request reached a protected endpoint without a valid session. | `"Unauthorized."`        |

When you receive a `401` on any endpoint other than `/api/admin/me`, your session has expired or was never established. Call `POST /api/admin/login` again to obtain a new session before retrying.

<Note>
  Validation errors on the login request (e.g. missing `email` or malformed email format) are returned as HTTP 422 with a Laravel validation error body, separate from the invalid-credentials 422 shown above.
</Note>

<Warning>
  Store your admin credentials securely. Never commit email/password values to source control or expose them in client-side code. Rotate passwords immediately if they are compromised.
</Warning>