Skip to main content

Authentication

All API requests (except /health) require a Bearer token in the Authorization header.

API key format

Keys use the prefix avat_live_ followed by a random string:

Using the SDKs

Install the official SDK for your language:
Initialize the client with your API key. Both SDKs also read the AVATCADO_API_KEY environment variable as a fallback if no key is passed directly.

Test keys

Test keys use the prefix avat_test_ and enable test mode. With a test key:
  • No upstream VIES/HMRC calls are made
  • No quota is consumed
  • Rate limit headers are omitted
  • Responses include meta.mode: "test"
  • Magic VAT numbers and magic EORI numbers return predictable scenarios

How keys are stored

API keys are hashed with SHA-256 before storage. Avatcado never stores your raw key. This means:
  • If you lose your key, it cannot be recovered. You’ll need to generate a new one
  • Even if the database were compromised, your key cannot be reversed

Identify your integration

The API records the User-Agent product name and version of the software that calls it, counted per key. Only the first two product tokens are kept, so acme-erp/1.2 (Windows NT 10.0) is stored as acme-erp/1.2. We use this for support and compatibility: when something changes or breaks, we can tell which integrations are affected. Send a descriptive User-Agent in the form name/version with every request:
Requests with no User-Agent are recorded as (none). Each key keeps at most 25 distinct values.

What happens without a valid key

Every error response includes a docs_url pointing to the relevant error page.