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.

Get a key

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

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.