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: 
avat_live_a1b2c3d4e5f6g7h8i9j0

​
Using the SDKs

Install the official SDK for your language: 
npm install @avatcado/node   # Node.js
pip install avatcado          # Python
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. 
import Avatcado from "@avatcado/node";

// Pass the key directly
const avatcado = new Avatcado("avat_live_your_api_key");

// Or set AVATCADO_API_KEY in your environment and omit the argument
const avatcado = new Avatcado();

​
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 return predictable scenarios
avat_test_a1b2c3d4e5f6g7h8i9j0

​
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

​
What happens without a valid key

ScenarioResult
No Authorization header401 - unauthorized
Invalid or revoked key401 - unauthorized
Wrong format (not Bearer)401 - unauthorized
Every error response includes a docs_url pointing to the relevant error page.