Authentication

Every request carries a Bearer token. The SDKs pick it up from LEGALIZE_API_KEY automatically; raw HTTP callers set the Authorization header explicitly.

Quota periods

Free quota resets on the 1st at 00:00 UTC. Pro quota follows the subscription start date: 50,000 requests per paid month, including twelve monthly quotas with annual billing. Unused requests do not roll over. API and MCP share the same quota. The dashboard and X-RateLimit-Reset show the next boundary.

Get a key

Keys are created from the dashboard. They start with leg_. First tier is free — no card, no expiration, 2,000 calls/month.

One key per environment. Don't share the same key between staging and production. Generate separate ones from the dashboard so you can revoke one without breaking the other.

Environment variables

Every official SDK honors the same three variables with the same precedence rules. This is the canonical contract — it's versioned in the repo and every SDK release ships with a parity test suite that asserts the same behaviour.

Variable	Required	Default
`LEGALIZE_API_KEY`	yes, unless passed as `apiKey`	—
`LEGALIZE_BASE_URL`	no	`https://legalize.dev`
`LEGALIZE_API_VERSION`	no	`v1`

Precedence: explicit constructor argument ≻ env var ≻ built-in default. Empty-string env vars (LEGALIZE_BASE_URL="") fall through to the default. Prefix LEGALIZE_ is mandatory — no short aliases, to avoid clashes with other SDKs in the same pod.

Raw HTTP

curl

curl -H "Authorization: Bearer leg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ "https://legalize.dev/api/v1/countries"

Errors

A malformed or missing key returns 401:

response

HTTP/1.1 401 Unauthorized Content-Type: application/json { "error": "invalid_api_key", "message": "API key missing or malformed" }

The SDKs raise AuthenticationError before the first network call if the key is missing or doesn't start with leg_ — no round trip wasted. See Errors & retries.

Rotating a key

Rotate from the dashboard. The old key is revoked immediately; any in-flight request using it gets a 401 on the next attempt. Deploy the new key (update the secret in your deploy environment), then revoke — that minimizes the blast radius if the old one leaked.