Authentication Overview

Xe uses OAuth 2.0 authorization flows that lets your app access a user’s account without accessing their password. OAuth 2.0 protocol is used for secure API access and supports multiple use cases. Xe API uses JWT access token to authenticate requests. You can obtain a new JWT token using below the OAuth flows and store the JWT to make further calls to secure endpoints.

Authorization Code Flow

Best for third-party applications acting on behalf of other businesses. Use this flow if you are building a platform integration or need users to explicitly grant access to their Xe accounts from your platform.

Register your redirect URLs with Xe

Send an email at xemtapi@xe.com with below information:

Environment: Sandbox or Production
Redirect URL: the URL on your server to redirect back to, the registered redirect URL should meet the below required criteria
- The redirect URL should be accessible in public
- It should take a query parameter named code which would contain a CSRF token issued by Xe. Example: https://clientname.com/xe-login-success?code=
- Redirect URL should be secure with HTTPS

Send a user to Xe to authorize your app

Your app/website should direct users to the following URL for Sandbox and production respectively.

Sandbox

https://sandbox-account.xe.com/signin?redirect_uri={{your-redirect-url}}&platform=ERP

Production

https://account.xe.com/signin?redirect_uri={{your-redirect-url}}&platform=ERP

Users are redirected back to you with a code

If the user authorizes your app, Xe will redirect back to your specified redirect_uri with a short-lived code (CSRF token) that can only be exchanged once and is valid for 60 seconds after issuance.

Sample redirection

https://{{your-redirect-url}}?code={{xe-returned-short-lived-code}}

Obtain JWT Token

You can now exchange the code for an access token by making a POST request based on the environment

Sandbox

https://launchpad-api-sandbox.xe.com/oauth2/apitoken

Production

https://launchpad-api.xe.com/oauth2/apitoken

The following values should be passed in as the request body:

client_id: use 3pi9u28grlkkuighl81fdvgrh7 for Production and 40u4hvergum85d9rtg00838v2e for Sandbox
grant_type: authorization_code
redirect_uri: your registered redirect URL ({{your-redirect-url}})
code: {{xe-returned-short-lived-code}}

Sample request in Sandbox

curl --location -g \
  --request POST 'https://launchpad-api-sandbox.xe.com/oauth2/apitoken' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=40u4hvergum85d9rtg00838v2e' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'redirect_uri={{your-redirect-url}}' \
  --data-urlencode 'code={{xe-returned-short-lived-code}}'

Sample request in Production

curl --location -g \
  --request POST 'https://launchpad-api.xe.com/oauth2/apitoken' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=3pi9u28grlkkuighl81fdvgrh7' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'redirect_uri={{your-redirect-url}}' \
  --data-urlencode 'code={{xe-returned-short-lived-code}}'

Sample Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEwMCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEwMCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEwMCJ9...",
  "expiresAt": "2025-11-05T17:24:56.1187695+00:00"
}

Token Expiry

All tokens received have an associated expiry time. Access tokens and refresh tokens can be exchanged prior to expiry.

access_token: 60 minutes
refresh_token: 30 days

Best practice: refresh tokens before expiry to avoid interruptions.

Authenticate API Requests

Authenticate

Xe API uses a JWT token to authenticate requests. To make authenticated API calls, use the Bearer Token you obtained in the previous step within your request header for all the requests.

The access_token part of the token response should be used to authenticate and authorize.

curl -L -X "$HTTP_METHOD" "$PAY_API_URL$REQUEST_PATH" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Get new JWT token using refresh token

To obtain a fresh JWT access_token using an existing refresh_token a POST request can be made as detailed below.

Request

curl --location -g --request POST '$PAY_API_URL/v2/auth/refresh' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "refreshToken": "$refresh_token"
  }

Response

{
   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEwMCJ9...",
   "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEwMCJ9...",
   "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEwMCJ9..."
   "expiresAt": "2025-11-05T17:24:56.1187695+00:00"
}

Getting started