Authentication

Authentication

Get started by authenticating your application with the Xama API.

Overview

The Xama API uses OAuth2 authentication with client credentials grant flow. This guide walks you through obtaining and using authentication credentials to make authenticated API calls.

Prerequisites

Before you begin, you’ll need a Xama account. You can create a free account at:

https://platform.xamatech.com

Step 1: Obtain Your API Credentials

Once your account is created, navigate to the Open API settings page to retrieve your OAuth credentials:

https://platform.xamatech.com/portal/hub/settings/apps/open-api

Here you will find:

• Application ID (client_id)
• Application Secret (client_secret)

Keep these credentials secure and never expose them in client-side code or public repositories.

Step 2: Request an Access Token

To authenticate API requests, you must first obtain an access token using your OAuth credentials.

Authentication Endpoint

POST https://auth-proxy.xamatech.com/oauth/token

Request Example

curl -X POST "https://auth-proxy.xamatech.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_oauth_id",
    "client_secret": "your_oauth_secret",
    "audience": "https://api.xamatech.com",
    "grant_type": "client_credentials"
  }'

Request Parameters

Parameter	Type	Required	Description
client_id	string	Yes	Your Application ID from the Xama portal
client_secret	string	Yes	Your Application Secret from the Xama portal
audience	string	Yes	Must be https://api.xamatech.com
grant_type	string	Yes	Must be client_credentials

Response

A successful request returns an access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Note that the response does not carry an expiry. See Token management for how to determine the token’s lifetime.

Step 3: Use the Access Token

Once you have an access token, include it in the Authorization header of all subsequent API requests.

API Base URL

All API endpoints use the following base URL:

https://xamahub.xamatech.com

Authentication Header Format

Authorization: Bearer {access_token}

Example Authenticated Request

curl -X GET "https://xamahub.xamatech.com/api/clients/{clientId}/accounts" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Client ID in API Endpoints

Many Xama API endpoints require a {clientId} parameter in the URL path. This represents your Xama Hub client identifier and is different from the OAuth client_id used for authentication.

Endpoint Structure

API endpoints follow this pattern:

https://xamahub.xamatech.com/api/clients/{clientId}/[resource]

Example Endpoints

• Search clients: GET /clients/{clientId}/search
• Create account: POST /clients/{clientId}/accounts
• Get risk assessments: GET /clients/{clientId}/accounts/{accountId}/risk-assessments

Finding Your Client ID

Your client ID can be found in the Xama platform or returned when you first authenticate and set up your integration. This ID should be stored securely in your application configuration.

Complete Example

Here’s a complete workflow showing authentication and an authenticated API call:

# Step 1: Get access token
TOKEN_RESPONSE=$(curl -X POST "https://auth-proxy.xamatech.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_oauth_id",
    "client_secret": "your_oauth_secret",
    "audience": "https://api.xamatech.com",
    "grant_type": "client_credentials"
  }')

# Step 2: Extract the access token
ACCESS_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.access_token')

# Step 3: Make authenticated API call
curl -X GET "https://xamahub.xamatech.com/api/clients/{your_client_id}/accounts" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Token management

The token response does not include an expiry field. The lifetime is carried inside the access token itself, as the exp claim of the JWT.

Handle this in two layers:

1. Read exp from the token. Decode the JWT payload and use exp to refresh proactively, shortly before it lapses. Do not assume a fixed lifetime; read the value from each token you receive.
2. Treat 401 as expired. If any API call returns 401 Unauthorized, request a fresh token and retry the call once.

The second layer is what makes the integration robust. Clock skew, a revoked credential or a configuration change can all invalidate a token before its exp would suggest, so do not rely on the expiry alone. Equally, do not retry indefinitely: if the retried call also returns 401, the credentials themselves are the problem and the integration should surface that rather than loop.