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

# Authentication API

> Login, token refresh, logout, and password reset endpoints.

## POST /api/auth/login

Authenticate a user and receive an access + refresh token pair.

**Public — no token required.**

### Request body

```json theme={null}
{
  "username": "admin@worshipharvest.org",
  "password": "password123",
  "churchName": "demo"
}
```

| Field        | Type   | Required | Description                                      |
| ------------ | ------ | -------- | ------------------------------------------------ |
| `username`   | string | Yes      | User's email or username                         |
| `password`   | string | Yes      | User's password                                  |
| `churchName` | string | Yes      | Tenant slug (church name, lowercased, no spaces) |

### Response

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "admin@worshipharvest.org",
    "contact": { "id": 1, "person": { "firstName": "John", "lastName": "Doe" } },
    "roles": ["Admin"],
    "permissions": ["contacts:read", "groups:manage"]
  }
}
```

***

## GET /api/auth/me

Returns the profile of the currently authenticated user.

**Requires:** Bearer token.

### Response

```json theme={null}
{
  "id": 1,
  "username": "admin@worshipharvest.org",
  "roles": ["Admin"],
  "permissions": ["contacts:read", "groups:manage"]
}
```

***

## POST /api/auth/refresh

Exchange a refresh token for a new access + refresh token pair.

**Requires:** Bearer token (the access token, even if expired, or just the refresh token — depending on server config).

### Request body

```json theme={null}
{
  "refreshToken": "eyJhbGci..."
}
```

### Response

```json theme={null}
{
  "accessToken": "eyJhbGci...",
  "refreshToken": "eyJhbGci..."
}
```

***

## POST /api/auth/logout

Invalidates the current session.

**Requires:** Bearer token.

### Response

```json theme={null}
{ "message": "Logged out successfully" }
```

***

## POST /api/auth/forgot-password

Sends a password reset link to the user's registered email.

**Public — no token required.**

### Request body

```json theme={null}
{ "username": "admin@worshipharvest.org" }
```

### Response

```json theme={null}
{
  "message": "If an account exists for that address, a reset link has been sent."
}
```

***

## PUT /api/auth/reset-password/:token

Sets a new password using the token from the reset email.

**Public — no token required.**

### Path parameter

| Parameter | Description                     |
| --------- | ------------------------------- |
| `token`   | Reset token from the email link |

### Request body

```json theme={null}
{ "password": "NewSecurePass@123" }
```

Passwords must meet complexity requirements (minimum length, mixed case, digits, special characters).

### Response

```json theme={null}
{ "message": "Password updated successfully." }
```