Authentication

All Pagamio VAS API endpoints (except the auth endpoints themselves) require a valid Bearer token in the Authorization header.

Obtain An Access Token

Endpoint: POST /auth/token

Request Body:

{
  "username": "your_api_username",
  "password": "your_api_password"
}

Successful Response:

{
  "successful": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
    "expiresIn": 1800
  }
}

Token Lifetimes

Token	Lifetime
Access token	30 minutes
Refresh token	7 days

Use the access token in every request:

Authorization: Bearer <ACCESS_TOKEN>

Refresh An Access Token

When the access token is close to expiry (or you receive a 401), exchange your refresh token for a new pair.

Endpoint: POST /auth/token/refresh

Request Body:

{
  "refreshToken": "<REFRESH_TOKEN>"
}

The response shape is identical to /auth/token.

Recommended Client Pattern

1. On startup, call /auth/token to obtain an access + refresh token pair.
2. Cache both tokens in memory (do not persist to disk in plain text).
3. Before each request, check the access token expiry. If less than 5 minutes remain, refresh.
4. If any request returns 401, refresh once and retry the request.
5. If the refresh call also returns 401 (refresh token has expired or been revoked), call /auth/token again with the credentials.

See Bearer Token Management for code examples and Access & Permissions for what each role can do.

Public Endpoints (No Token Required)

• POST /auth/token
• POST /auth/token/refresh
• POST /users/forgotpassword
• POST /users/resetpassword

---

Last updated: April 2026