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

1. Obtain a Token

$
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:

1
{
2
  "token": "eyJhbGciOiJIUzM4NCJ9...",
3
  "expiresIn": 3600
4
}

2. Use the Token

Include the token in every request:

$
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:

1
{
2
  "username": "admin",
3
  "fullName": "John Doe",
4
  "email": "john.doe@nms.go.ug",
5
  "roles": ["ROLE_FACILITY_USER"],
6
  "facilityCode": "HF0124"
7
}

Token Expiry & Refresh

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.

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