Ayrexa API

Overview

A read-only REST API for Enterprise organisations to pull their own invoices and customers into other systems, and signed webhooks that tell you the moment something happens.

Base URL

https://api.ayrexa.com

Version

1.0.0

Authentication

Sign in as an organisation administrator and open Settings > API Keys. API access needs the Enterprise plan.

Send the key in the X-Api-Key header of every request. Only a hash of the key is stored, so it cannot be shown again after it is created. Create a new key if you lose it, and revoke any key you no longer use.

Send it from your server, never from a browser or a mobile app, and never put it in a URL.

Key format: aur_live_ followed by 48 lowercase hexadecimal characters

curl "https://api.ayrexa.com/api/public/v1/invoices" \
  -H "X-Api-Key: aur_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Pagination

Out-of-range values are corrected, not rejected: page below 1 is read as 1 and pageSize is held between 1 and 200. total is the number of items across all pages, so the last page is ceil(total / pageSize).

Every list answers { total, page, pageSize, items }.

Reading every page

async function* allInvoices() {
  for (let page = 1; ; page++) {
    const response = await fetch(`https://api.ayrexa.com/api/public/v1/invoices?page=${page}&pageSize=200`, {
      headers: { 'X-Api-Key': process.env.AYREXA_API_KEY },
    });
    if (response.status === 429) {
      await new Promise(r => setTimeout(r, Number(response.headers.get('Retry-After') ?? 60) * 1000));
      page--;
      continue;
    }
    if (!response.ok) throw new Error(`Ayrexa API answered ${response.status}`);
    const body = await response.json();
    yield* body.items;
    if (page * body.pageSize >= body.total) return;
  }
}

Rate limits

600 requests per minute. Per client IP address, shared with every other request from that address to the Ayrexa API.

429 Too Many Requests with no body and a Retry-After header giving the seconds to wait. Wait for Retry-After, then resume. Fetch pages one after another rather than in parallel.

Errors

Problem details

Endpoints

curl "https://api.ayrexa.com/api/public/v1/invoices?page=1&pageSize=50" \
  -H "X-Api-Key: $AYREXA_API_KEY"

const response = await fetch('https://api.ayrexa.com/api/public/v1/invoices?page=1&pageSize=50', {
  headers: { 'X-Api-Key': process.env.AYREXA_API_KEY },
});
if (!response.ok) throw new Error(`Ayrexa API answered ${response.status}`);
const { total, page, pageSize, items } = await response.json();

using var http = new HttpClient { BaseAddress = new Uri("https://api.ayrexa.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("AYREXA_API_KEY"));

using var response = await http.GetAsync("/api/public/v1/invoices?page=1&pageSize=50");
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

{
  "total": 57,
  "page": 1,
  "pageSize": 20,
  "items": [
    {
      "invoiceNumber": "INV-0021",
      "customerName": "BCX",
      "invoiceDate": "2026-09-01T00:00:00Z",
      "totalAmount": 11500,
      "currencyCode": "ZAR",
      "status": "Posted"
    },
    {
      "invoiceNumber": "INV-0020",
      "customerName": "Karoo Fresh Produce",
      "invoiceDate": "2026-08-28T00:00:00Z",
      "totalAmount": 2875.5,
      "currencyCode": "ZAR",
      "status": "Paid"
    }
  ]
}

curl "https://api.ayrexa.com/api/public/v1/customers?page=1&pageSize=50" \
  -H "X-Api-Key: $AYREXA_API_KEY"

const response = await fetch('https://api.ayrexa.com/api/public/v1/customers?page=1&pageSize=50', {
  headers: { 'X-Api-Key': process.env.AYREXA_API_KEY },
});
if (!response.ok) throw new Error(`Ayrexa API answered ${response.status}`);
const { total, page, pageSize, items } = await response.json();

using var http = new HttpClient { BaseAddress = new Uri("https://api.ayrexa.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("AYREXA_API_KEY"));

using var response = await http.GetAsync("/api/public/v1/customers?page=1&pageSize=50");
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

{
  "total": 12,
  "page": 1,
  "pageSize": 20,
  "items": [
    {
      "id": "b7d5e0c4-9a21-4c3e-8f0a-52e6d1a94c70",
      "name": "BCX",
      "email": "ap@bcx.example",
      "country": "South Africa"
    },
    {
      "id": "0c6a8f52-71de-4a49-b3b8-1d9c4e27f605",
      "name": "Karoo Fresh Produce",
      "email": null,
      "country": "South Africa"
    }
  ]
}

Webhooks

Instead of polling, register an HTTPS endpoint under Settings > Webhooks (organisation administrators, Enterprise plan) and Ayrexa sends it a signed POST when something happens.

Events

{
  "event": "invoice.created",
  "data": {
    "invoiceId": "3f1c1b6e-2d4a-4f6e-9a57-8c1d2e0b7a11",
    "invoiceNumber": "INV-0021",
    "customerId": "b7d5e0c4-9a21-4c3e-8f0a-52e6d1a94c70",
    "totalAmount": 11500,
    "currencyCode": "ZAR",
    "status": "Draft"
  },
  "sentAt": "2026-11-11T08:30:00Z"
}

{
  "event": "invoice.paid",
  "data": {
    "invoiceId": "3f1c1b6e-2d4a-4f6e-9a57-8c1d2e0b7a11",
    "invoiceNumber": "INV-0021",
    "amountPaid": 11500,
    "paymentDate": "2026-11-12T00:00:00Z"
  },
  "sentAt": "2026-11-12T09:15:00Z"
}

What Ayrexa sends

POST with a application/json body: { "event": string, "data": object, "sentAt": ISO 8601 UTC timestamp }

Verify the signature

• Algorithm: HMAC-SHA256. sha256=<lowercase hex digest>
• Key: The endpoint's signing secret exactly as it was shown when you created the endpoint, starting whsec_, taken as UTF-8 text. It is shown once.
• Message: The raw request body, byte for byte as received. Verify before you parse it: re-serialising JSON changes the bytes.
• Compare in constant time. A request whose signature does not match was not sent by Ayrexa: answer 401 and ignore it.

import crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.AYREXA_WEBHOOK_SECRET; // "whsec_..." exactly as shown when you created the endpoint
const app = express();

// The signature covers the exact bytes Ayrexa sent, so read the raw body. Do not re-serialise parsed JSON.
app.post('/ayrexa-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const received = Buffer.from(req.get('X-Ayrexa-Signature') ?? '');
  const expected = Buffer.from(
    'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex'));

  if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) {
    return res.sendStatus(401);
  }

  const delivery = JSON.parse(req.body.toString('utf8'));
  // delivery.event, delivery.data, delivery.sentAt
  res.sendStatus(200);
});

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

app.MapPost("/ayrexa-webhook", async (HttpRequest request) =>
{
    // The signature covers the exact bytes Ayrexa sent, so read the raw body.
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);
    var body = buffer.ToArray();

    var secret = Environment.GetEnvironmentVariable("AYREXA_WEBHOOK_SECRET")!; // "whsec_..." exactly as shown
    var expected = "sha256=" + Convert.ToHexString(HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), body)).ToLowerInvariant();
    var received = request.Headers["X-Ayrexa-Signature"].ToString();

    if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(received), Encoding.UTF8.GetBytes(expected)))
        return Results.Unauthorized();

    var delivery = JsonDocument.Parse(body).RootElement; // event, data, sentAt
    return Results.Ok();
});

import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["AYREXA_WEBHOOK_SECRET"].encode()  # "whsec_..." exactly as shown when you created the endpoint


@app.post("/ayrexa-webhook")
def ayrexa_webhook():
    body = request.get_data()  # the exact bytes Ayrexa sent
    expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Ayrexa-Signature", "")

    if not hmac.compare_digest(received.encode(), expected.encode()):
        abort(401)

    delivery = request.get_json()  # delivery["event"], delivery["data"], delivery["sentAt"]
    return "", 200

Delivery and retries

• Any 2xx answer. Answer quickly and do the work afterwards.
• Deliveries are queued and sent by a sweep that runs about every two minutes, so allow a few minutes for one to arrive.
• Up to 5 attempts in all. After a failed attempt (any answer that is not 2xx, a timeout or a connection error) the next one is made after 1 minute, then 5 minutes, then 30 minutes, then 2 hours; after the fifth failure the delivery is given up.
• A retry sends the original body again, with the original sentAt, so sentAt is when the event happened, not when it was delivered. Deliveries can arrive more than once and out of order: make your handler idempotent, for example by remembering the event and data.invoiceId pairs you have handled.

Versioning and changelog

v1 The version is the second path segment (/api/public/v1). Within a version we only add: new endpoints, new optional query parameters, new response fields and new webhook events. A change that could break a client ships under a new version (for example /api/public/v2) and leaves this one as it is. Ignore response fields you do not recognise.