Skip to navigation

Authentication

View as Markdown

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

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

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:

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

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:

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

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.

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.

RoleAccess
ROLE_FACILITY_USERFacility-scoped operations (orders, stats, deliveries)
ROLE_REVIEWEROrder review and approval workflows
ROLE_ADMINFull 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