Authentication

API Key Authentication

All API requests require an API key passed in the X-API-Key HTTP header. You can create and manage API keys from the developer dashboard.

Making Authenticated Requests

Include your API key in every request:

curl -X GET "https://api.aribatax.com/v1/counties" \
  -H "X-API-Key: your_api_key_here"

Key Security Best Practices

• Never expose your API key in client-side code. Use it only in server-side applications or environment variables.
• Use IP allowlists (Growth tier and above) to restrict which IP addresses can use your key.
• Rotate keys regularly. The dashboard supports zero-downtime key rotation with a 24-hour grace period for the old key.
• Use separate keys for development and production environments.

Key Rotation

When you rotate a key, a new key is generated immediately. The previous key remains valid for 24 hours to prevent downtime during deployment. After 24 hours, the old key is automatically revoked.

To rotate a key:

1. Go to API Keys in your dashboard
2. Click the Rotate button on the key
3. Copy the new key value (shown only once)
4. Update your application configuration
5. Deploy before the 24-hour grace period expires

Error Responses

If your API key is missing or invalid, you will receive a 401 Unauthorized response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key. Include a valid X-API-Key header."
  }
}

If your key is valid but your account has been suspended or rate limited, you will receive a 403 Forbidden or 429 Too Many Requests response respectively.

Multiple Keys

You can create multiple API keys to separate usage across different applications or environments. Each key tracks its own usage statistics. The number of keys you can create depends on your plan tier:

| Tier | Max Keys | |------------|----------| | Free | 2 | | Starter | 5 | | Growth | 5 | | Enterprise | 10 |