Skip to content

Session Management

Session Tokens

After authenticating via GET /helo or POST /auth, you receive a session token (xa-token). This token must be passed as a Bearer token on every subsequent API request.

Authorization: Bearer <xa-token>

Session tokens are short-lived. When a token expires, the API returns 403 Access denied. Your client should detect this and re-authenticate to obtain a new token.

The Nonce Parameter

To protect against replay attacks and duplicate submissions, all write operations (POST and PUT endpoints) require a nonce query parameter.

Rules

  • Must be a positive integer (int64)
  • Must be strictly greater than the nonce used in the previous request within the same session
  • Must be unique per request — reusing a nonce will result in a rejection

Using the current Unix timestamp in milliseconds is a simple and reliable strategy:

const nonce = Date.now(); // e.g. 1700000000001

Or in Python:

import time
nonce = int(time.time() * 1000)

Example

POST /api/03101176/v4.0.0/invoices?nonce=1700000000001
Authorization: Bearer <xa-token>
Content-Type: application/json

Nonce is required on POST and PUT

Omitting the nonce on a write operation will result in a 400 Invalid input response.

Checking Session Health

Use GET /status to verify your session is valid and to inspect version information and any recent errors:

GET /api/03101176/v4.0.0/status
Authorization: Bearer <xa-token>

The response includes:

  • status — human-readable health summary (e.g. "ready - login: john, company: Demo")
  • server_time — current server time (ISO 8601)
  • versions — called API version vs current server version
  • errors — any recent errors in this session context

Handling Token Expiry

def make_request(url, token, api_token):
    response = requests.get(url, headers={"Authorization": f"Bearer {token}"})
    if response.status_code == 403:
        # Re-authenticate
        new_token = get_session_token(api_token)
        response = requests.get(url, headers={"Authorization": f"Bearer {new_token}"})
    return response