Alpha testing: all current functionality is free while VAT Engine is in active development

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 / capabilityfullcalculate-onlyread-onlyclassification-resolveclassification-write
VAT calculation (POST /v1/vat/calculate, POST /v2/vat/calculate)YesYesNoNoNo
VAT rates (GET /v1/vat/rates)YesNoYesNoNo
Transactions (GET /v1/transactions/*)YesNoYesNoNo
Source profile reads (GET /v1/sources, GET /v1/sources/unknown)YesNoYesNoNo
Source profile writes (POST /v1/sources, PATCH /v1/sources/{id})YesNoNoNoNo
Threshold check (POST /v1/vat/threshold-check)YesNoYesNoNo
Threshold status (GET /v1/compliance/threshold-status)YesNoYesNoNo
CN/CPA resolution (POST /v1/tax-class/resolve)YesNoNoYesNo
CN/CPA assignment submissionYesNoNoNoYes

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

  1. Go to Dashboard → API Keys
  2. Click Create Key and choose a scope
  3. 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

StatusMeaning
401Missing or invalid API key
403Key scope doesn't allow this endpoint
429Rate 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.