Skip to main content

​
Authentication

All API requests (except /v1/health) require a Bearer token in the Authorization header.

​
API key format

Keys use the prefix vtly_live_ followed by a random string: 
vtly_live_a1b2c3d4e5f6g7h8i9j0

​
Test keys

Test keys use the prefix vtly_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
vtly_test_a1b2c3d4e5f6g7h8i9j0

​
How keys are stored

API keys are hashed with SHA-256 before storage. Vatly 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

ScenarioResult
No Authorization header401 — unauthorized
Invalid or revoked key401 — unauthorized
Wrong format (not Bearer)401 — unauthorized
Every error response includes a docs_url pointing to the relevant error page.