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: /health, /ready, GET /v1/vat/thresholds, GET /v1/vat/sme-thresholds, POST /v1/vat/sme-eligibility, GET /v1/tax-classes.
Some deployment-owned platform callback routes can also be publicly reachable without API keys. For example, Shopify OAuth callbacks and Shopify webhook/privacy receivers are system-to-system ingress points for the configured app, not general customer API endpoints, so they are documented with the Shopify integration flow instead of in this authentication guide.
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: vat_production_your_key_here"Scopes
Each API key has a scope that defines which endpoints it can access:
| Endpoint / capability | full | calculate-only | read-only |
|---|---|---|---|
VAT calculation (POST /v1/vat/calculate) | Yes | Yes | No |
VAT rates (GET /v1/vat/rates) | Yes | No | Yes |
Transactions (GET /v1/transactions/*) | Yes | No | Yes |
Source profile reads (GET /v1/sources, GET /v1/sources/unknown) | Yes | No | Yes |
Source profile writes (POST /v1/sources, PATCH /v1/sources/{id}) | Yes | No | No |
Threshold check (POST /v1/vat/threshold-check) | Yes | No | Yes |
Threshold status (GET /v1/compliance/threshold-status) | Yes | No | Yes |
Choose the smallest scope that fits your integration to follow the principle of least privilege.
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
Overview of VAT Engine integrations, including connection models, source mapping, token handling, and platform-specific setup guidance for external stores.