Skip to main content

​
Access: API keys

​
What this is for

An API key is a long secret password that your software sends with every request so the API knows who is calling. The Access page is where you create keys, see which ones exist and how much each is used, and revoke any that leak or are no longer needed. Every key belongs to one project. There are two kinds, and the difference matters:
  • A test key (clk_test_…) works against the sandbox, a safe practice environment. Use it while you build. It is free on every plan.
  • A live key (clk_live_…) works against real production data and is only available on paid plans. Use it only from your own deployed backend.

​
Before you start

  • Only an organization owner or admin can create or revoke keys. Everyone else can see the list.
  • Decide where the key will live. It should go into your server’s secret manager or an environment variable, never into a web page, mobile app or code repository.
  • A suspended project refuses new keys until its open invoice is paid.

​
Create a key

1

Open Access

Choose Access in the sidebar. The page is titled Access: “API keys: create and manage the secrets your servers use to call the API. Every key has a Test or Live environment and fixed scopes.”
2

Start a new key

In the Test keys card select Create test key. (The Create live key button in the Live keys card only appears on a paid plan.) A panel titled Create test key opens.
3

Name it

Type a Name (up to 80 characters), such as Backend service. The name is only for you, so you can tell keys apart later.
4

Choose scopes

Under Scopes tick what the key may do. Read (“Fetch and search records (GET requests).”) and Write (“Create, update and delete records (POST, PUT, PATCH, DELETE). Does not allow reading them back.”) are both ticked by default. A key that must create a record and then fetch it needs both. Scopes are fixed once the key exists; to change them, create a new key.
5

Create

Select Create key (it reads Creating… briefly).
6

Copy it now

The panel changes to Key created: “Copy it now. For your security it is shown only this once.” Select Copy key and paste it into your secret manager. Then select Done.

​
Revoke a key

1

Find the key

In its table, find the row. Use the View link first if you want to see what the key has been doing in Logs.
2

Revoke

Select the bin icon on the row (screen readers call it Revoke key plus the key’s name). A confirmation titled Revoke API key asks: “Revoke “name”? Anything using it stops working immediately. This cannot be undone.”
3

Confirm

Select Revoke key. A message says Key “name” revoked, and the row disappears.

​
What you’ll see

At the top, a grey note: Keep keys on your server. It repeats that keys are shown in full once. Two cards, Test keys (“Work against the sandbox. Free to use on every plan.”) and Live keys (“Work against production data. Available on paid plans.”). Each lists keys in a table: Empty states: No test keys yet (“Create a test key to make your first request.”), No live keys yet (“Create a live key when you are ready for production.”), and on the Free plan Live keys need a paid plan with a See plans button. If a Free-plan project still has live keys from before, they stay listed with the note “These live keys no longer work on the Free plan. You can revoke them here…”. If you are not an owner or admin: Only an organization owner or admin can create or revoke keys.

​
Common questions

A test key talks to a sandbox full of practice (fictional) data and is free. A live key talks to real production data and needs a paid plan. They look alike but start with different words: clk_test_ and clk_live_. Build and test with test keys; switch to a live key only when your code is ready for real patients.
For safety, the dashboard stores only a fingerprint of the key, not the key. Nobody, including us, can show it again. If you lose it, revoke it and make a new one.
Most apps need both Read and Write. Choose Read only for a reporting tool that must never change data. Remember Write alone cannot read records back.
Send it in an x-api-key header on every request. See Authentication and the snippet on Overview.
No. It only stops that key from working. Records are untouched.
Create one per service so that you can revoke one without breaking the others.

​
Troubleshooting