Getting started

Authentication and keys

How API keys work, what a key can do, and how to keep one safe.

Every request to the API needs an API key. Keys are made in the dashboard by an owner, an admin or a developer of your organization.

Make a key#

Sign in and open Developers.
Under Create an API key, give the key a name (Staging, Local dev), choose a mode and tick its permissions.
Choose Create key and copy the key. It is shown once. Claim House keeps only a one-way hash of the secret, so a lost key cannot be shown again: revoke it and make another.

A key looks like this, with a key ID, a dot and a secret:

Text

ch_test_<key id>.<secret>

Send the key#

Send it as a bearer token on every request:

Shell

curl "https://sandbox.myclaimhouse.com/api/v1/me" -H "Authorization: Bearer $CLAIMHOUSE_KEY"

GET /me answers with the key itself: its name, its mode, its permissions and the organization it belongs to. It is the quickest way to check that a key works. See Get the current key.

Mode: test or live#

A key is for one organization and one mode.

A test key (ch_test_...) reads and writes sandbox data only. Eligibility checks are answered by a scripted sandbox payer, chosen by the subscriber's member ID. Nothing reaches a payer and nothing is billed. See Sandbox and scenarios.
A live key (ch_live_...) is for real payers. Live mode is not open yet: see Going live.

A key sees only the data of its own mode. A test key cannot read a live check, and an office made for live mode cannot be used with a test key.

Permissions#

A key has read, submit, or both.

Permission	Allows
`read`	Every `GET`: payers, offices, providers, checks, claims (their timelines and 837D), events, webhook endpoints, the sandbox scenarios.
`submit`	Every request that creates, changes or deletes something: running a check, sending, changing, resubmitting or voiding a claim, adding or changing a provider, adding or removing a webhook endpoint, replaying an event. A key with `submit` alone changes only the claims it made, and reads a claim only in the answers to its own writes.

The two are separate on purpose. An integration that only submits checks still needs a key that can read, for one job: after a 504 TIMEOUT it must look up the check it may have made (see Errors, retries and idempotency). Give it a second, read-only key for that.

A request the key is not allowed to make is refused with 403 PERMISSION_DENIED.

When a key is refused#

A missing, malformed, unknown or revoked key all get the same answer, 401 UNAUTHORIZED, so the answer does not tell a caller which of them it was.

JSON

{
  "error": "UNAUTHORIZED",
  "message": "A valid API key is required. Send it as \"Authorization: Bearer <key>\".",
  "errors": [],
  "request_id": "req_..."
}

Keep keys safe#

Keep a key on your server. Never put one in a browser, a mobile app or a repository.
Make one key for each integration or environment, so you can revoke one without touching the others.
Revoke a key in the dashboard as soon as it may have leaked. A revoked key stops working at once, and an api_key.revoked event is recorded.
Never put patient information in an Idempotency-Key or a tenant_reference. The key is stored and kept in the request log; the reference is stored on the check and sent in its events to your webhook endpoints.