Authentication

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

Response

A successful request returns an access token:

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

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

Token Expiration

Access tokens expire after 15 minutes. A new access token should be requested using the appropriate credentials.