Authentication Guide

All Exirom API requests require an authenticated token, which must be included in the HTTP request headers. Clients receive this token by authenticating via the /auth endpoint using the credentials provided by the Exirom Admin Team.

To retrieve your token, visit this /v1/authpage from the API Reference.

The Exirom Platform utilizes JSON Web Token (JWT) for authentication to authorize access to its API securely. This document outlines the complete authentication flow, including how to obtain and use your credentials and token

Authentication Flow

Step 1: Obtain Credentials

Before accessing the API, you must request credentials from the Exirom platform administrators.
These credentials typically consist of:

• Username (or Email)
• Password (auto-generated or manually assigned)

⚠️

Keep these credentials secure. Do not share or expose them in client-side applications.

Step 2: Authenticate via ${host}/v1/auth Endpoint

Send a POST request to the ${host}/v1/auth endpoint you need to provide your Merchant Key and Merchant Secret to obtain an access token.

Endpoint: POST${host}/v1/auth

Request Headers: Content-Type: application/json

{
   "merchantKey": "5df49***********aa5",
   "merchantSecret": "i9rqY***********8kXmuA"
}

curl -X POST https://${host}/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "merchantKey": "5df49***********aa5",
    "merchantSecret": "i9rqY***********8kXmuA"
  }'

{
    "merchantKey": "5df495f********************aa5",
    "token": "eyJhbGci************bOVf8XiWCjPy9k"
}

To retrieve your token, visit this /v1/authpage from the API Reference.

Step 3: Use the Token in API Requests

Once the token is retrieved, include it in the Authorization header of all subsequent API requests.

GET /v1/payments/card
Host: https://${host}/
Authorization: Bearer <token>

Token Format

• The token is a standard JWT string.
• It is base64-encoded and contains claims about the authenticated user.
• The token must be passed as-is in the Authorization header with the prefix Bearer.

Token Expiration

By default, tokens are valid for a specific duration (e.g., 24 hours), after which re-authentication is required. If your token expires, repeat Step 2 to generate a new one.

Let us know if you require refresh tokens or longer expiration support.

Error Handling

{
  "error": "Invalid username or password"
}

{
  "error": "Unauthorized"
}

Handle 401 Unauthorized responses gracefully and re-authenticate if necessary.

Best Practices

• Store the token securely (e.g., in environment variables or secure storage).
• Never expose credentials or tokens in public repositories or frontend code.
• Re-authenticate when you receive a 401 response.
• Use HTTPS for all API communication to prevent token leakage.

Need Help?

If you're experiencing issues with authentication or your token is not working, contact the Exirom support team or your assigned administrator.