JWT Authentication Flow

eAPI-Auth is an authentication service responsible for issuing and refreshing tokens used by OLS applications.

It follows a JWT-based authentication model using short-lived access tokens and longer-lived refresh tokens to balance security, performance, and reliability.

Authentication Overview

The authentication flow is based on a dual-token strategy:

  • accessToken

    • Used to authorize API requests
    • Short-lived (5 minutes)
    • Sent in every request

  • refreshToken

    • Used to obtain a new accessToken without re-authenticating
    • Longer-lived (30 minutes)
    • Used only when needed

This model reduces the need for frequent authentication while limiting exposure if a token is compromised.

Authentication Flow

  1. Client authenticates using credentials
  2. Server returns accessToken and refreshToken
  3. Client uses accessToken for API calls
  4. When expired, client uses refreshToken
  5. Server returns a new pair of tokens
  6. Client replaces stored tokens

Requesting an Access Token

Endpoint
POST /v0/auth/token

Description
Authenticates the client and returns a new pair of tokens.

Request Body

{
  "username": "string",
  "password": "string"
}

Response

{
  "status": {
    "code": "Success",
    "timestamp": "2025-01-29T11:52:25Z",
    "description": "Success"
  },
  "accessToken": "<access_token_jwt>",
  "expiresIn": 300,
  "refreshToken": "<refresh_token_jwt>",
  "refreshExpiresIn": 1800,
  "tokenType": "Bearer",
  "sessionState": "<session_id>"
}

Usage

Authorization: Bearer <access_token_jwt>

Refreshing an Access Token

Endpoint
POST /v0/auth/token/refresh

Description
Generates a new accessToken and refreshToken using a valid refreshToken.

Request Body

{
  "refreshToken": "<refresh_token_jwt>"
}

Response

{
  "status": {
    "code": "Success",
    "timestamp": "<timestamp>",
    "description": "Success"
  },
  "accessToken": "<access_token_jwt>",
  "expiresIn": 300,
  "refreshToken": "<refresh_token_jwt>",
  "refreshExpiresIn": 1800,
  "tokenType": "Bearer",
  "sessionState": "<session_id>"
}

Token Lifecycle and Behavior

  • Tokens are stateless JWTs
  • Expiration is enforced by the server
  • A refreshed token invalidates the previous pair (clients must not reuse old tokens)
  • Clients should always replace both tokens after refresh

Recommended Token Management Strategy

  1. No accessToken available
    → Call POST /v0/auth/token

  2. accessToken is still valid (≤ 5 minutes)
    → Reuse it

  3. accessToken has expired

  4. If refreshToken is valid (≤ 30 minutes)
    → Call POST /v0/auth/token/refresh
    → Replace both tokens
  5. If refreshToken has expired
    → Call POST /v0/auth/token

Error Handling (Recommended)

Clients should handle authentication failures gracefully:

  • 401 Unauthorized
  • Cause: accessToken expired or invalid

  • Action: attempt token refresh

  • 401 on refresh endpoint

  • Cause: refreshToken expired or invalid

  • Action: re-authenticate using credentials

  • Repeated failures

  • Action: log and alert (possible credential or system issue)

Best Practices

  • Cache and reuse tokens until expiration
  • Avoid requesting a new token for every request
  • Always replace tokens after refresh
  • Store refreshToken securely (server-side if possible)
  • Do not expose tokens in logs or URLs
  • Implement retry logic using refresh before re-authentication

Notes

  • Requesting a new token periodically (e.g., every ~10 hours) is sufficient
  • If refresh fails, fall back to POST /v0/auth/token