Authentication & environments
TaxLens has two ways to authenticate a request — an interactive JWT for the dashboard, and an org-scoped API key for your backend. Each rides on its own header.
Base URL
Every endpoint lives under a single host. Examples in these guides use the production base URL:
https://api.taxlens.getdynamiq.aiPaths are versioned under /v1 (for example POST /v1/tax/calculate). The unversioned GET /health probe returns service status and is unauthenticated. There is no separate sandbox host — you isolate test traffic with the is_test flag on bookings rather than a different URL. See Test vs live for how the test fiscal series keeps sandbox invoices from touching real numbering.
Two ways to authenticate
The two modes use different headers — a JWT goes in Authorization: Bearer, an API key goes in X-API-Key. The deeper difference is who is acting and what they can reach.
| Field | Type | Description |
|---|---|---|
| JWT (session token) | interactive | Issued when a person logs in. This is how the dashboard authenticates every call you see in the in-app calculator, booking list, and invoice views. The token carries the user and their active organization, which is refreshed from the database on each request — so a revoked membership stops working immediately rather than at token expiry. Short-lived; not meant to be embedded in a backend. |
| API key | machine-to-machine | A long-lived, org-scoped credential you generate in the dashboard for server-side integration. The key is pinned to the organization it was created in and does not drift if the creator later switches orgs. API access is enabled during onboarding; if you do not see the key management screen, ask your TaxLens contact to switch it on. See API keys (dashboard). |
Sending the credential
A server-side integration sends its org-scoped API key in the X-API-Key header. (The interactive JWT instead goes in Authorization: Bearer <jwt>; an API key passed there fails the JWT check and returns 401.)
curl https://api.taxlens.getdynamiq.ai/v1/jurisdictions/US-NY-NYC \
-H "X-API-Key: $TAXLENS_KEY"What an API key can and cannot reach
An API key is scoped to ordinary org resources — calculating tax, validating addresses, managing properties, persisting bookings, issuing invoices, and pulling reports. It cannot reach organization-management surfaces: inviting members, changing roles, managing other API keys, or editing the org's legal profile. Those actions are for a signed-in admin and require a JWT.
Next
With auth sorted, see Errors & idempotency for how failures and retries are shaped, then jump to Calculate tax for your first real call. New to the model itself? Start with Core concepts.