Authorization

Every request to the Relay API must be authenticated. Authentication uses a static key/secret pair that you generate once and include on every request — there are no sessions or tokens to refresh.

Credentials

When you create an API user in the platform, you receive two values:

Sending a Request

Include both headers on every API call.

curl -X GET https://api.numis-trust.com/relay/v1/accounts \
  -H "x-api-key: numis_abc123xyz789" \
  -H "x-api-secret: your-api-secret" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.numis-trust.com/relay/v1/accounts', {
  method: 'GET',
  headers: {
    'x-api-key': process.env.NUMIS_API_KEY,
    'x-api-secret': process.env.NUMIS_API_SECRET,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

Permissions

Each API user is issued a fixed set of permissions at creation time. The platform admin can update them at any time. Every endpoint documents the exact permission it requires.

If a credential is missing the required permission for an endpoint, the API returns 403 Forbidden. The response body identifies the issue:

{
  "message": "Missing required API scope: Initiate account transactions"
}

Error Reference

Rate Limiting

Requests are rate-limited per API key. When the limit is reached the API returns 429 Too Many Requests with headers to guide retry timing.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716652800