> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://apidocs.nms.go.ug/llms.txt.
> For full documentation content, see https://apidocs.nms.go.ug/llms-full.txt.

# Authentication

> How to authenticate with the NMS API Platform using JWT Bearer tokens.

# Authentication

The NMS API Platform uses **JSON Web Token (JWT)** authentication. Every request (except health checks) must include a valid token in the `Authorization` header.

## Authentication Flow

```mermaid
sequenceDiagram
    participant Client
    participant API as NMS API Gateway
    Client->>API: POST /api/v1/auth/login<br />{username, password}
    API-->>Client: 200 OK<br />{token, expiresIn}
    Client->>API: GET /api/v1/master/facilities<br />Authorization: Bearer <token>
    API-->>Client: 200 OK (data)
    Note over Client,API: Token expires after `expiresIn` seconds
    Client->>API: GET /api/v1/orders/...<br />Authorization: Bearer <expired_token>
    API-->>Client: 401 Unauthorized
    Client->>API: POST /api/v1/auth/login<br />{username, password}
    API-->>Client: 200 OK (new token)
```

## 1. Obtain a Token

```bash
curl -X POST https://testapi.nms.go.ug/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'
```

**Response:**

```json
{
  "token": "eyJhbGciOiJIUzM4NCJ9...",
  "expiresIn": 3600
}
```

## 2. Use the Token

Include the token in every request:

```bash
curl -X GET https://testapi.nms.go.ug/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzM4NCJ9..."
```

## 3. Verify Your Identity

Use the `/api/v1/auth/me` endpoint to confirm your token is valid and inspect your user profile:

```json title="GET /api/v1/auth/me Response"
{
  "username": "admin",
  "fullName": "John Doe",
  "email": "john.doe@nms.go.ug",
  "roles": ["ROLE_FACILITY_USER"],
  "facilityCode": "HF0124"
}
```

## Token Expiry & Refresh

<Warning>
  Tokens expire after the duration specified in the `expiresIn` field (in seconds). There is no refresh token mechanism — you must re-authenticate by calling the login endpoint again.
</Warning>

**Best practices:**

* Cache the token and reuse it until it expires
* If you receive a `401 Unauthorized` response, re-authenticate
* Do not hardcode tokens — always obtain them at runtime

## Roles & Permissions

Access to API endpoints is governed by the roles assigned to your user account. The `roles` field in the `/api/v1/auth/me` response indicates your permission level.

| Role                 | Access                                                 |
| -------------------- | ------------------------------------------------------ |
| `ROLE_FACILITY_USER` | Facility-scoped operations (orders, stats, deliveries) |
| `ROLE_REVIEWER`      | Order review and approval workflows                    |
| `ROLE_ADMIN`         | Full platform access                                   |

## Endpoints Without Authentication

The following endpoints do **not** require a JWT token:

* `GET /actuator/health` — API Gateway health check
* `GET http://localhost:8081/actuator/health` — Auth Service health check
* `GET http://localhost:8083/actuator/health` — Order Service health check