Authentication
All API requests (except/health) require a Bearer token in the Authorization header.
API key format
Keys use the prefixavat_live_ followed by a random string:
Using the SDKs
Install the official SDK for your language:AVATCADO_API_KEY environment variable as a fallback if no key is passed directly.
Test keys
Test keys use the prefixavat_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 theUser-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:
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.