Skip to main content
Every request to a versioned endpoint (/v1/...) in production must include a valid API key. Keys are free; create one in the dashboard, or from your project’s folder with the haau3 CLI: npx haau3 login, then npx haau3 keys create, which writes the key to the project’s env file and never shows it. The Sandbox, the API’s test environment at sandbox.haau3.com, also answers calls with no key.

API keys

  • Keys are organization-scoped, and each works in one mode: a live key looks like haau3_sk_live_… and a test key like haau3_sk_test_… (see test and live keys).
  • A key’s secret is shown once at creation on the dashboard, and never by the CLI, which writes it to the env file instead. Store it securely. If it’s lost, revoke it and create a new one.
  • Keys are stored hashed at rest, so haau3 cannot recover a secret after it’s shown.

Test and live keys

When you create a key on the dashboard’s API keys page, you choose where it works: A test key cannot reach production and a live key cannot reach the Sandbox, so code under test never calls a production service by mistake. Both kinds belong to your organization. A live key’s requests count toward its plan’s requests a minute and a month. A test key’s requests in the Sandbox count toward a minute of their own, at the plan’s number and apart from your production requests, and never toward the month, so your Sandbox calls cannot slow your production calls or use up your allowance. A key made before test keys looks like haau3_sk_…, with neither live nor test. It works in production and at /v1/sandbox/fhir/r4 until it is replaced, and the API keys page shows its mode as “Live and test”. sandbox.haau3.com takes test keys only, so such a key gets a 401 there.

A key in the wrong mode

A key sent where its mode does not work returns 403 with WWW-Authenticate: Bearer realm="api.haau3.com", error="insufficient_scope" and a code that says which: test-key-outside-sandbox or live-key-in-sandbox, from https://haau3.com/fhir/CodeSystem/api-error. On a FHIR base the code is in the OperationOutcome’s issue.details.coding; anywhere else it is the problem’s code. The key is checked first, so a key that is not recognised is still a 401, and a 403 always means a real key in the wrong place. Send the request again with a key of the other mode.

Sending your key

Send the key as a Bearer token in the Authorization header:

The Sandbox without a key

The Sandbox’s own host, https://sandbox.haau3.com, answers a request with no key at all, so you, or your coding agent, can make a first call before signing up:
Each IP address may make 30 such requests an hour, an IPv6 address counted by its /64. The 31st is a 429 with a Retry-After header, which runs to the end of that address’s hour, and a free test key raises the limit to your plan’s requests a minute. A request has no key only when it sends neither an Authorization header nor x-api-key. A key that is not a working test key, or one sent any other way than Authorization: Bearer, is a 401, never served as a call with no key, and an IP address (an IPv6 address by its /48) that sends 30 keys within an hour that are not recognised gets a 429 for its keyed requests until that hour ends. Calling the Sandbox accepts haau3’s terms: send test data only, never a real person’s. The Sandbox has the rest. Production always needs a key.

The 401 contract

A missing key, or one that is not recognised, returns 401 Unauthorized with a WWW-Authenticate header and a body in the shape of the endpoint you called. The text says which of the two happened. At sandbox.haau3.com a missing key is served instead. A request to production with no key, for example:
When a key was sent and not recognised, the text begins “The API key was not recognised” and the header adds error="invalid_token". Errors, limits and request ids describes both shapes. A valid key in its own mode returns 200. A key belongs to its organization, and every request it sends counts toward the organization’s plan: a live key’s toward its requests a minute and a month, a test key’s toward a minute of the Sandbox’s own. A request past one of the plan’s limits answers 429; limits has each plan’s numbers. The Developer plan is free.

Keeping keys safe

Treat API keys like passwords. Don’t commit them to source control or expose them in client-side code. Use server-side requests or a secrets manager, and revoke any key you believe is compromised.