Skip to content
TaxQL Docs

Authentication

Every request requires an X-API-Key header with your API key. Authorization: Bearer <key> is also accepted for compatibility with existing HTTP-client conventions; either header works on every endpoint.

Terminal window
curl -H "X-API-Key: your-key-here" \
     "https://api.taxql.com/v1/tax/tx?zip=75068"
from taxql import TaxQL
client = TaxQL(api_key="your-key-here")

The Python SDK sets the header for you when you pass api_key= to the constructor.

Getting a key

Section titled “Getting a key”

Sign up at taxql.com/signup for a 14-day trial with 1,000 lookups. A card is required to start the trial but is not charged during it — you’re only billed if you continue to a paid plan. Your API key is shown immediately and accessible from the dashboard at any time at app.taxql.com.

Key management

Section titled “Key management”
  • Rotate at app.taxql.com/keys. New keys are issued instantly; old keys remain valid until you explicitly revoke them so you can roll forward without downtime.
  • Storage. Treat your key like a password. Load it from an environment variable or secret manager in production; never commit to source control. The SDK reads from whatever you pass — it has no default key lookup.
  • Per-environment keys. Use distinct keys for production vs staging/CI so you can revoke one without affecting the other.
  • Tier ceiling. Your key’s tier determines the monthly lookup quota. (Premium address resolution is on for every plan, including the trial.) The response includes a billing block with the resolved tier so you can verify in code.

When the key is wrong

Section titled “When the key is wrong”

The API returns 401 with a structured error block when the key is missing or invalid:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid X-API-Key.",
    "support_reference": "req_..."
  }
}

error.code is UNAUTHORIZED in both cases; error.message distinguishes a missing key (“Missing credentials…”) from one that doesn’t match an account (“Invalid X-API-Key.”). The Python SDK maps this to AuthError — catch it and prompt the user to re-enter their key rather than retrying blindly.

Next

Section titled “Next”