Skip to main content

Authentication

The Integration API uses API Key/Secret Key authentication with JWT-based access tokens and refresh tokens.

Authentication Flow​

  1. Get API Credentials: Obtain your API Key and Secret Key from the Brokerage platform
  2. Authenticate: Use your credentials to get an access token and refresh token
  3. Use Access Token: Include the access token in the Authorization header for API requests
  4. Refresh Token: When the access token expires, use the refresh token to get a new access token

Authenticate​

Authenticate with your API key and secret key to receive access and refresh tokens.

Endpoint: POST /api/v1/integration/auth/authenticate

Request​

You can send credentials either in the request body or as headers:

Required Header:

X-Target-Server: authentication

Option 1: Request Body

{
  "api_key": "your-api-key",
  "secret_key": "your-secret-key"
}

Option 2: Headers

Api-Key: your-api-key
Api-Secret: your-secret-key

Example cURL Request​

Option 1: Request Body

curl -X POST https://<base-url>/api/v1/integration/auth/authenticate \
  -H "Content-Type: application/json" \
  -H "X-Target-Server: authentication" \
  -d '{
    "api_key": "your-api-key",
    "secret_key": "your-secret-key"
  }'

Option 2: Headers

curl -X POST https://<base-url>/api/v1/integration/auth/authenticate \
  -H "X-Target-Server: authentication" \
  -H "Api-Key: your-api-key" \
  -H "Api-Secret: your-secret-key"

Response​

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "abc123def456...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2025-01-03T12:00:00Z"
}

Response Fields​

  • access_token: JWT token for API authentication (valid for 1 hour)
  • refresh_token: Token to refresh the access token (valid for 7 days)
  • token_type: Always "Bearer"
  • expires_in: Access token expiration time in seconds (3600 = 1 hour)
  • expires_at: Access token expiration timestamp

Using the Access Token​

Include the access token in the Authorization header for all protected endpoints. Also include the X-Target-Server header:

Authorization: Bearer <access_token>
X-Target-Server: integration

Example cURL Request​

curl -X GET https://<base-url>/api/v1/integration/<endpoint> \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Target-Server: integration"

Note: Authentication endpoints (/auth/authenticate and /auth/refresh) use X-Target-Server: authentication, while all other endpoints use X-Target-Server: integration.

Refresh Token​

Refresh your access token when it expires.

Endpoint: POST /api/v1/integration/auth/refresh

Request​

Required Header:

X-Target-Server: authentication
{
  "refresh_token": "abc123def456..."
}

Example cURL Request​

curl -X POST https://<base-url>/api/v1/integration/auth/refresh \
  -H "Content-Type: application/json" \
  -H "X-Target-Server: authentication" \
  -d '{
    "refresh_token": "abc123def456..."
  }'

Response​

Same format as the authenticate endpoint, returning a new access token and the same refresh token.

Error Responses​

Invalid Credentials (401)​

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "invalid api key or secret"
  }
}

Expired Refresh Token (401)​

{
  "error": {
    "code": "REFRESH_TOKEN_EXPIRED",
    "message": "refresh token expired"
  }
}

Webhook Authentication Types​

When configuring webhooks (for markets, distributors, etc.), you can specify the authentication type using the type field in the authentication object.

Authentication Type Values​

TypeValueDescription
Basic1HTTP Basic Authentication using username and password
Token2Token-based authentication

Example: Basic Authentication​

{
  "authentication": {
    "type": 1,
    "username": "user",
    "password": "pass"
  }
}

Example: Token Authentication​

{
  "authentication": {
    "type": 2,
    "token": "your-token-here"
  }
}