Authentication

All API requests require authentication using a Bearer token obtained from the /auth/login endpoint. The authentication flow ensures that only authorized applications and users can access protected resources such as terminals, e-wallet channels, and transfer operations.

The API adopts a two-token strategy for secure access. Upon successful login, the client receives a short-lived access_token for API requests and a long-lived refresh_token to obtain new access tokens without re-authenticating.

Authentication Flow

1. Login
Send your credentials (posId and password) to /auth/login.
You’ll receive an access token and a refresh token.

2. Use Access Token
Include the access token in the Authorization header for all subsequent API requests.

3. Refresh Token
When the access token expires, call /auth/refresh to obtain a new one without re-login.

4. Logout (optional)
Invalidate tokens and terminate the session using /auth/logout.

Token Types

Token Type	Description	Expiry
Access Token	Used for API authorization. Must be sent in the Authorization header as Bearer <token>.	15 minutes or at 12 AM (whichever earlier)
Refresh Token	Used to obtain a new access token when expired. Should be stored securely (never in browser localStorage).	Expires at 12 AM

Example Requests

1. Login (Obtain Tokens)

POST /auth/login
Content-Type: application/json

{
  "posId": "fiuuPos1",
  "password": "yourStrongPassword"
}

Response

{
  "access": {
    "token": "eyJhbGciOiJIUzI1NiIsInR...",
    "expiresAt": "YYYY-MM-DDTHH:mm:ss.SSS±HH:mm"
  },
  "refresh": {
    "token": "eyJhbGciOiJIUzI1NiIsInR...",
    "expiresAt": "YYYY-MM-DDTHH:mm:ss.SSS±HH:mm"
  }
}

2. Refresh Token

POST /auth/refresh
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...

Response

{
  "access": {
    "token": "eyJhbGciOiJIUzI1NiIsInR...",
    "expiresAt": "YYYY-MM-DDTHH:mm:ss.SSS±HH:mm"
  },
  "refresh": {
    "token": "eyJhbGciOiJIUzI1NiIsInR...",
    "expiresAt": "YYYY-MM-DDTHH:mm:ss.SSS±HH:mm"
  }
}

3. Using Access Token

All authorized requests must include the Authorization header.

GET /api/terminals
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...

Security Best Practices

1. Always use HTTPS (TLS 1.2 or higher)
Never send credentials or tokens over plain HTTP.

2. Do not expose tokens in URLs or logs
Keep tokens in headers only.

3. Store tokens securely

• On mobile: use secure storage (Keychain / Keystore).
• On server: encrypt or store in a secure session store.

4. Rotate tokens regularly
Refresh tokens periodically to maintain secure sessions.

5. Handle Expired Tokens Gracefully
APIs will return 401 Unauthorized if a token is invalid or expired. The client should automatically call /auth/refresh.

Common Error Responses

HTTP Code	Error	Description
400	invalid_request	Missing or malformed parameters.
401	unauthorized	Token is missing, invalid, or expired.
403	forbidden	Account suspended or deleted.
429	rate_limit_exceeded	Too many requests — slow down.
500	internal_server_error	Internal server error occured