Authentication & environments
Developer keys, scopes, sandbox and live, and what a key may do.
Every request authenticates with an organization-owned developer key. The key names the organization, the granted scopes, and — implicitly — the environment, because a key is bound to exactly one.
The Authorization header
Send the key as a bearer token. Do not put it in a query string, and do not ship it to a browser or a mobile client.
Authorization: Bearer vat_sandbox_REPLACE_WITH_YOUR_KEY
Content-Type: application/jsonScopes
Grant the narrowest set an integration needs. A key that lacks the scope for an operation receives 403 SCOPE_FORBIDDEN naming the missing scope — never a generic failure.
| Field | Type | Description |
|---|---|---|
vat:validate | vat_validation | Validate a VAT identifier against the authority. |
company:search | company_search · company_resolution | Search a certified company source and resolve a partial identity. |
company:verify | company_verification | Verify a registry-qualified legal entity and compare claims. |
vat:discover | vat_discovery | Discover sourced VAT associations for a legal entity. |
history:read | verification history | Read canonical completed responses for the organization and environment. |
Environments
sandbox uses deterministic fixtures and consumes no live authority capacity. live calls the authority and the configured sources. Every operation accepts either environment except company resolution, which requires live.
- Sandbox evidence is labelled
sandbox_fixtureand a synthetic source name, so it can never be presented as a live observation. - A key for the wrong environment returns
403 ENVIRONMENT_FORBIDDEN. Switch the key, not the request body. - History is partitioned by environment; a sandbox check never appears in a live history query.
When authentication fails
401 UNAUTHORIZED— the token is missing, malformed, expired, or revoked. Stop using it and reissue a key.403 SCOPE_FORBIDDEN— the key is valid but lacks the operation's scope. Grant the scope or use another key.403 ENVIRONMENT_FORBIDDEN— the key belongs to the other environment.403for organization or commercial access — the organization cannot use this operation or source yet.