Browse the documentation

Issuing a key

Name it, grant it scopes, list its addresses and choose an expiry of 90, 120 or 320 days.

DevelopersLast updated

A Tenant API key belongs to your organisation, not to a person. It acts under what it was granted, from the addresses on its allowlist, until it expires, is rotated or is revoked. Issue keys under Settings, then API Keys.

What you choose

  • A name, so you can tell keys apart in the usage and audit records.
The Create an API key window with a name filled in, the Used with choices, De-identify patients, and the Access table where new keys start read-only.
  • Scopes: the operations and opt-in fields the key may use.
The Create an API key window scrolled to the Access table, the Sensitive fields choices for patient identifiers and clinical text, Expires after, Requests per minute and Restrict to sites.
  • Sites, if the key should be confined to some of them. Leave this empty for every site.
  • An IP allowlist. It is required, with at least one address or CIDR range.
  • An expiry of 90 days (the default), 120 days or 320 days. No other lifetime is accepted.
  • A per-minute rate limit, up to your tenant's ceiling.
The bottom of the Create an API key window, with Expires after, Requests per minute, Restrict to sites and the Allowed IP addresses box filled in.

You cannot grant more than you could do yourself. If your own role cannot edit appointments, for example, a key you issue cannot hold appointments:update.

The secret is shown once

The secret starts with cr_live_ and appears only in the response to issuing or rotating the key. Store it in your secrets manager straight away. Clarirad keeps a hash and cannot show it again.

Calling the API

Send the secret as a bearer token to your region's host. A key works only in the region that issued it.

# Australia
curl https://api.clarirad.com/api/external/v1/patients \
  -H "Authorization: Bearer cr_live_..."

# Chile
curl https://api-cl.clarirad.com/api/external/v1/patients \
  -H "Authorization: Bearer cr_live_..."

Expiry, rotation and revocation

  • An expired key is refused with 401 and API key has expired.
  • Rotating gives a new secret with the same grant and the same lifetime. The old secret keeps working for an overlap period, 24 hours by default, so you can change over without downtime.
  • A revoked key is refused with 401 and API key has been revoked.

A key can never manage keys, sign reports, delete records or administer users. Those routes do not exist on this API.