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();

from avatcado import Avatcado

# Pass the key directly
avatcado = Avatcado("avat_live_your_api_key")

# Or set AVATCADO_API_KEY in your environment and omit the argument
avatcado = 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

Scenario	Result
No `Authorization` header	`401` - unauthorized
Invalid or revoked key	`401` - unauthorized
Wrong format (not Bearer)	`401` - unauthorized

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

Getting Started

Core Concepts

Guides

Errors

Authentication

Authentication

API key format

Using the SDKs

Test keys

How keys are stored

What happens without a valid key

​Authentication

​API key format

​Using the SDKs

​Test keys

​How keys are stored

​What happens without a valid key

Authentication

API key format

Using the SDKs

Test keys

How keys are stored

What happens without a valid key