Authentication
Authenticating with the VAT Engine API using API keys
All /v1/* endpoints require an API key unless marked as public. Public endpoints: /health, /ready, GET /v1/vat/thresholds, GET /v1/vat/sme-thresholds, POST /v1/vat/sme-eligibility, GET /v1/tax-classes.
API Key Header
Pass your key in the X-API-Key header on every request:
curl "https://api.vat-engine.daily-automations.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
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.
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.