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

# Authentication

> PASETO Bearer Tokens, Refresh Flow, and PIN Login

## Overview

The EmaalCoin API uses **PASETO** bearer tokens for authentication. Obtain tokens via login endpoints and send them in the `Authorization` header.

## Token Types

| Token             | Lifetime     | Purpose                   |
| ----------------- | ------------ | ------------------------- |
| **Access Token**  | \~15 minutes | Authenticate API requests |
| **Refresh Token** | Long-lived   | Obtain new access tokens  |

## Login Endpoints

### Email + Password

```http theme={null}
POST /api/v1/users/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}
```

Returns **`access_token`** and **`refresh_token`** (PASETO).

### PIN Login

```http theme={null}
POST /api/v1/users/login-pin
Content-Type: application/json

{
  "email": "user@example.com",
  "pin": "123456"
}
```

Or with phone number:

```json theme={null}
{
  "phone_number": "+254712345678",
  "pin": "123456"
}
```

## Refresh Token Flow

When the access token expires, exchange the refresh token for new tokens:

```http theme={null}
POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "<your_refresh_token>"
}
```

<Warning>
  Refresh token rotation is enabled. The old refresh token is revoked immediately after use. Always use the new refresh token returned in the response for future refreshes.
</Warning>

## Using the Token

Add the access token to every protected request:

```http theme={null}
Authorization: Bearer v2.local.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

## PIN Management

* **Set during registration**: Include `pin` in `POST /api/v1/users/register`
* **Update existing PIN**: `PUT /api/v1/auth/user/id/{id}/pin`

## Unauthenticated Endpoints

These endpoints do not require a token:

* `POST /api/v1/users/register`
* `POST /api/v1/users/login-pin`