API keys and scopes

Creating, scoping, restricting, rotating and revoking a CuspFlow API key, how a key's bound staff role sets a hard ceiling on what it can ever do, and the rate limits that apply to every plan.

An Owner or Administrator creates an API key under Settings → Integrations → API.

A key looks like this:

cfk_live_a3k9m2p7_xTnQ4vL8ZrB2wK7mD9sF1gH5jN0pC6yE3aU

The first part is a non-secret lookup prefix, which is what you see listed in Settings and in your activity log. The long part after it is the secret.

The secret is shown once, at creation. We store only a hash of it and cannot recover or re-display it. If you lose it, rotate the key.

Send it as a bearer token on every request:

curl -H "Authorization: Bearer cfk_live_a3k9m2p7_xTnQ..." \
  "https://zwhwryofdsgmzgqbcghl.supabase.co/functions/v1/api/v1/patients?limit=50"

Two layers decide what a key can do

The role is the ceiling. Every key is bound to a staff role when you create it, and the database enforces that role on every single query the key makes, exactly as it would for a person logged into the app. A key bound to Receptionist cannot read payroll no matter how you scope it. A key can never be bound to Owner.

The scopes narrow it from there. Give a reporting key patients:read and nothing else, and that is all it will ever touch, even though its role could do more.

The practical consequence: scope a key to the smallest thing that does its job, and bind it to the least powerful role that holds that permission. A nightly BI extract wants a read-only role and read-only scopes. A migration needs an Administrator, and only for as long as the migration takes.

The scopes

Scope Grants
patients:read Patients, families, patient insurance
patients:write Create and edit those
clinical:read Medical history, patient journey
clinical:write Create and edit medical history
appointments:read Appointments
appointments:write Create and edit appointments
appointments:delete Delete an appointment, separate on purpose
treatment:read Treatment plans and their items
treatment:write Create and edit treatment plans
billing:read Invoices, payments, claims, insurance carriers
billing:totals Clinic-wide financial aggregates
inventory:read Inventory items, batches, stock movements
inventory:write Create and edit inventory items
catalog:read Services and prices
catalog:write Create and edit catalog items and insurance carriers
lab:read Lab cases, their procedures, laboratories
lab:write Create and edit laboratories
org:read Branches, chairs, staff directory
export:read Bulk extract endpoints
imports:write Start an import and push batches. Administrator only
imports:rollback Undo an import. Administrator only

A key can only hold a scope its bound role already has in the app. Ask for more and creation fails, naming the scopes that were refused, rather than quietly issuing a key that will 403 on its first real call.

appointments:delete is deliberately separate from appointments:write. An integration that reschedules appointments has no business removing them.

Restricting a key to branches

A key can be limited to one or more branches. It then returns only rows belonging to those branches.

One subtlety is worth understanding before you rely on it. A branch restriction applies to records of where something happened: appointments, treatment plans, payments, lab cases, the patient journey. It does not apply to patients or staff, because branch_id on a person is a durable fact (where a patient first registered, where a staff member is based for HR) and not a record of where anything took place. A patient who registered at your first branch and is treated at your second would otherwise disappear from the second branch's key, which is exactly the wrong answer.

So: branch-restrict a key to limit what activity it sees, not to partition your patient list.

Expiry, rotation and revoking

A key expires after at most 365 days. You get warning emails 30 days, 7 days and 1 day before, so a nightly job does not stop silently.

Rotate issues a new secret on the same key, keeping its name, scopes, branch limits and history. The old secret keeps working for 24 hours, so you can deploy the new one without a window of downtime, and the Settings page tells you whether anything is still calling with the old one.

Revoke takes effect immediately, on the next request, not at the end of an hour or a cache window. Revoked keys are kept forever as a record of what existed, and do not count against your limit.

A clinic can hold 10 active keys at a time. If you are near that, the usual cause is old keys nobody revoked; revoke rather than rotate when an integration is genuinely gone.

Rate limits

The same for every plan.

Limit Value
Requests per minute, per key 60
Burst 10 per second
Requests per day, per key 10,000
Requests per minute across all your keys 120
Page size 50 by default, 200 maximum
Request body 1 MiB, or 4 MiB on an import batch

Every response tells you where you stand:

RateLimit-Limit: 60
RateLimit-Remaining: 47
RateLimit-Reset: 60
RateLimit: limit=60, remaining=47, reset=60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 60

Both the newer RateLimit-* names and the older X-RateLimit-* aliases are sent, so whichever your HTTP client already understands will work.

Go over and you get 429 with Retry-After in seconds. Wait that long. Retrying straight into the limit in a loop just burns the day's allowance.

Failed requests count. The request log is the rate-limit counter, so a 403 or a 404 spends allowance exactly like a 200. A misconfigured job that is quietly erroring is still costing you quota, which is one good reason to look at your activity log.

The per-clinic ceiling of 120 a minute exists so one misbehaving key cannot starve the others.

At 60 requests a minute and 200 rows a page, a full extract of a 50,000-patient clinic takes about four minutes. If you need more for a one-off migration, ask us. Both limits are stored per key and we can raise yours without a code change.

Read-only clinics

If a subscription lapses into read-only, reads keep working at the full rate and writes return 403 with the code clinic_read_only. Your data never becomes unreachable because of a billing problem, which is the same policy that keeps CSV export available in the app.

meta/whoami reports this as "writable": false, so a migration script can check once up front instead of discovering it on row 400.

Your own activity log

Settings → Integrations → API → Activity lists every request made with your keys over the last 90 days: which key, which endpoint, the status code, how long it took. It is the right place to look when a nightly job has quietly stopped working.

We record the endpoint pattern rather than the full URL, and never request bodies or filter values, so the log itself holds no patient data.

Still stuck? Our team is happy to help.

Email support