Authentication
Authenticate to VAT Engine with scoped API keys, rotation guidance, rate-limit behavior, and the headers required for every protected endpoint.
Documented /v1/* API endpoints require an API key unless marked as public. Public documented endpoints include /health, /ready, GET /v1/vat/thresholds, GET /v1/vat/sme-thresholds, POST /v1/vat/sme-eligibility, GET /v1/tax-classes, and exact CN/CPA validation at GET /v1/classification-codes/{scheme}/{code}.
API Key Header
Pass your key in the X-API-Key header on every request:
curl "https://api.vat-engine.app/v1/vat/rates?country=DE&tax_class_id=standard" \-H "X-API-Key: YOUR_API_KEY"Scopes
Each API key has a scope that defines which endpoints it can access:
| Endpoint / capability | full | calculate-only | read-only | classification-resolve | classification-write |
|---|---|---|---|---|---|
VAT calculation (POST /v1/vat/calculate, POST /v2/vat/calculate) | Yes | Yes | No | No | No |
VAT rates (GET /v1/vat/rates) | Yes | No | Yes | No | No |
Transactions (GET /v1/transactions/*) | Yes | No | Yes | No | No |
Source profile reads (GET /v1/sources, GET /v1/sources/unknown) | Yes | No | Yes | No | No |
Source profile writes (POST /v1/sources, PATCH /v1/sources/{id}) | Yes | No | No | No | No |
Threshold check (POST /v1/vat/threshold-check) | Yes | No | Yes | No | No |
Threshold status (GET /v1/compliance/threshold-status) | Yes | No | Yes | No | No |
CN/CPA resolution (POST /v1/tax-class/resolve) | Yes | No | No | Yes | No |
| CN/CPA assignment submission | Yes | No | No | No | Yes |
Choose the smallest scope that fits your integration to follow the principle of least privilege.
Sandbox and Production Data
Sandbox keys created in your hosted dashboard use the same API endpoint,
https://api.vat-engine.app, and the same VAT calculation and validation rules.
The authenticated key selects the data environment; no environment parameter is needed.
Sandbox responses include X-VAT-Environment: sandbox; production responses include
X-VAT-Environment: production.
Sandbox calculations persist separate test history for your account. Sandbox keys can access only that sandbox history, source profiles, registrations, reports and exports. Production keys and the account dashboard use production data. Sandbox activity does not contribute to production financial or compliance totals. Test records remain sandbox data when you switch your integration to a production key.
Scopes apply in both environments: calculate-only permits calculations, while retrieving
history or reports requires a sandbox key with read-only or full scope. Idempotency keys
are separate between sandbox and production, and key rotation retains the existing environment.
Sandbox uses the same supported operations and evidence requirements; it does not make unknown
or unsupported tax treatment successful.
Key Lifecycle
Creating Keys
- Go to Dashboard → API Keys
- Click Create Key and choose a scope
- Copy the plaintext key immediately — it is shown only once
You can have up to 25 currently usable credentials at a time. Rotated keys still count during their grace window, so you may need to revoke an unused key or wait for the old rotated key to age out before creating another one.
Rotating Keys
When you rotate a key, the old key enters a 48-hour grace window during which both the old and new key are accepted. This allows you to update your integration without downtime.
Because both credentials remain valid during that overlap, rotation also requires one free key slot. If you are already at the usable-key cap, revoke an unused key or wait for another rotated key's grace window to expire first.
Revoking Keys
Revoking a key takes effect immediately. All requests using the revoked key will return 401 Unauthorized.
Rate Limits
- API Endpoints: 60 requests per minute per API key (configurable)
- Exceeding the limit returns
429 Too Many Requests
Error Responses
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Key scope doesn't allow this endpoint |
429 | Rate limit exceeded |
When a key is valid but lacks the required scope, the API returns 403 with error: "insufficient_scope". Create or rotate to a key with the smallest scope that covers the operation instead of broadening every integration key by default.
Quick Start
Create an account, generate an API key, send your first VAT calculation request, and find the next VAT Engine docs to explore in about five minutes.
Integrations
Learn how to connect supported stores to VAT Engine, map reporting sources, review connection health, and find platform-specific setup guidance.