Authentication

All API access begins with authentication. You exchange your credentials for a time-limited access token, which is then used for every subsequent request.

Prerequisites

Only requests from pre-approved IP addresses are allowed (production)
Send Authorization: Bearer <access_token> on all authenticated API calls
Pass X-REQUEST-ID (unique UUID) on every request for cross-system tracing

Base URLs

Environment	Base URL
Staging	`https://api.staging.rewardos.in`
Production	`https://api.rewardos.in`

POST /v1/partners/auth/login

Exchange your credentials for an access token. This endpoint does not require authentication.

Request Body

{
  "clientId": "string",
  "clientSecret": "string"
}

Response

Status 200 — Login successful:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresInSecs": 3600
}

Error Responses

Status	Meaning	Common Cause
`401`	Unauthorized	Wrong clientId/clientSecret, or staging keys on production
`400`	Bad Request	Missing fields in request body
`403`	Forbidden	Request from a non-whitelisted IP

Example Request

curl -X POST "https://api.staging.rewardos.in/v1/partners/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_STAGING_CLIENT_ID",
    "clientSecret": "YOUR_STAGING_CLIENT_SECRET"
  }'

Token Management

The access token expires after expiresInSecs (typically 3600s / 1 hour).

Cache the Token

Do not call Login before every request. Store the token and reuse it within the validity window.

let cachedToken = null;
let tokenExpiry = null;

async function getToken() {
  const now = Date.now();
  if (cachedToken && tokenExpiry && now < tokenExpiry - 300000) {
    return cachedToken;
  }

  const response = await fetch(`${process.env.REWARDOS_BASE_URL}/v1/partners/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: process.env.REWARDOS_CLIENT_ID,
      clientSecret: process.env.REWARDOS_CLIENT_SECRET,
    }),
  });

  const data = await response.json();
  cachedToken = data.token;
  tokenExpiry = now + data.expiresInSecs * 1000;
  return cachedToken;
}

Automatic Refresh

Refresh at ~80% of expiry (e.g. after 48 minutes for a 60-minute token).

Handle Mid-Session 401

If you receive a 401 during a request, re-authenticate and retry the failed request automatically.

Request Headers

Every API call after authentication must include:

Header	Value	Description
`Authorization`	`Bearer <access_token>`	JWT from Login
`X-REQUEST-ID`	Unique UUID per request	Required for support and tracing
`Content-Type`	`application/json`	Required for POST bodies

Example: Authenticated Request

curl -X GET \
  https://api.staging.rewardos.in/v1/partners/products \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'X-REQUEST-ID: a-unique-uuid-here'

Setup Checklist

Store clientId and clientSecret securely
Implement token acquisition via /v1/partners/auth/login
Implement refresh based on expiresInSecs
Include Authorization: Bearer {token} on all API calls
Generate and log unique X-REQUEST-ID for every request
Keep base URLs configurable per environment
Handle 401 by re-authenticating automatically