Authentication

vatnode uses API keys to authenticate requests. All API requests require a valid API key.

API Key Format

API keys follow this format:

vat_live_...  - Live keys — real VIES validation, counts against quota
vat_test_...  - Test keys — static responses, never counts against quota

Using Your API Key

Include your API key in the Authorization header with every request:

curl https://api.vatnode.dev/v1/vat/IE6388047V \
  -H "Authorization: Bearer vat_live_your_key_here"

Creating API Keys

1. Sign in to your Dashboard
2. Navigate to API Keys
3. Click "Create Key"
4. Enter a descriptive label (e.g., "Production Server", "Development")
5. Select the environment (live or test)
6. Click "Create"

Test Mode

Test keys (vat_test_...) are designed for integration tests and local development. They never touch VIES and never count against your monthly quota.

Use the reserved XX test VAT numbers below. They are guaranteed to never match a real company. All fields — including countryVat — are fully populated with synthetic data, so the response is structurally identical to a live response. Any other VAT number returns valid: false.

Example — valid VAT with full company data:

curl https://api.vatnode.dev/v1/vat/XX0000001 \
  -H "Authorization: Bearer vat_test_your_test_key"

{
  "valid": true,
  "vatId": "XX0000001",
  "countryCode": "XX",
  "countryName": "Test Country",
  "companyName": "Test Company Ltd",
  "companyAddress": "1 Test Street, Test City, TC1 0AA",
  "companyRegistrationDate": null,
  "companyForm": null,
  "industryDescription": null,
  "verifiedAt": "2026-04-01T10:00:00.000Z",
  "checkId": "019d2a89-a5d9-7b97-b710-57b84604de2b",
  "countryVat": {
    "vatName": "Value Added Tax",
    "vatAbbr": "VAT",
    "currency": "EUR",
    "standardRate": 10,
    "reducedRates": [9, 8, 7],
    "superReducedRate": 6,
    "parkingRate": 5,
    "vatNumberFormat": "XX + 7 digits",
    "vatNumberPattern": "^XX\d{7}$",
    "countryVatUpdatedAt": "2026-03-31"
  }
}

Managing API Keys

Viewing Keys

Go to Dashboard > API Keys to see all your keys. Each key shows:

• Label
• Key preview (first and last characters)
• Environment (live/test)
• Last used timestamp
• Created date

Deleting Keys

To delete a key:

1. Find the key in your API Keys list
2. Click the delete (trash) icon
3. Confirm the deletion

Security Best Practices

Keep Keys Secret

• Never commit API keys to version control
• Don't expose keys in client-side code
• Use environment variables to store keys

# .env file
VATNODE_API_KEY=vat_live_your_key_here

// Use environment variable
const apiKey = process.env.VATNODE_API_KEY;

Use Separate Keys

Create different keys for different environments and applications:

• Production Server - For your live production environment
• Development - For local development
• Staging - For staging/testing environments

This way, if one key is compromised, you can revoke it without affecting other environments.

Rotate Keys Regularly

For enhanced security, rotate your API keys periodically:

1. Create a new key
2. Update your application to use the new key
3. Verify the new key works
4. Delete the old key

Rate Limits

Authenticated requests (with a valid API key) are not rate-limited — send as many requests as your monthly quota allows. Unauthenticated requests (no API key or invalid key) are limited to 30 requests per minute per IP.

When you exceed your monthly quota, the behaviour depends on your plan:

• Free — requests are blocked with a 429 error. Upgrade to continue.
• Starter & Pro — requests continue at a pay-as-you-go overage rate (see table below), up to a monthly cap. Once the cap is hit, requests are blocked until the next billing cycle.
• Enterprise — unlimited, no quota, no overage.

You'll receive an email alert when you reach 80% of your overage cap.

Error Responses

Missing API Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key required. Include Authorization: Bearer {your_api_key}",
    "requestId": "req_abc123"
  }
}

Invalid API Key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or revoked API key",
    "requestId": "req_abc123"
  }
}