Get started
API keys & permissions
How keys work, what each permission (scope) allows, and how to keep keys safe.
How a key works#
Every request must carry a key in the Authorization header, written as the word Bearer, a space, and the key:
http
GET https://your-healthfix-site/api/v1/appointments
Authorization: Bearer hfk_2f9c…your-key…- A key acts as the person who created it, in their clinic, and can never do more than that person can do in the app.
- Scopes narrow it down further. A receptionist's key with only
appointments:readcan see appointments and nothing else. - Keys always start with
hfk_. Only the header works; keys in the web address or cookies are ignored, so they don't end up in logs. - If the person is deactivated, or signed out of all devices, their keys stop working too.
Scopes: what a key may do#
Tick only what the integration needs. You can always create another key later.
| Scope | Lets the key… | Who can grant it |
|---|---|---|
patients:read | Search patients and read their profile and visit summary. | Everyone |
patients:write | Register new patients and update their details. | Everyone |
appointments:read | See appointments, the OPD queue, doctors and their schedules. | Everyone |
appointments:write | Book, reschedule, check in, cancel and add walk-ins. | Everyone |
records:read | Read consultations, prescriptions, case history, vitals, lab results, care plans and notes. | Doctors and clinic admins only |
billing:read | Read invoices, payments, services and the billing summary. | Everyone |
inventory:read | Read pharmacy stock, expiry and low-stock alerts. | Everyone |
reports:read | Read dashboard numbers and practice reports. | Everyone |
Any valid key, whatever its scopes, may also read who it belongs to (GET /auth/me) and the clinic's basic settings such as timezone and currency.
What keys can never do
Sign in, manage staff or other keys, change clinic settings, upload files, export all data, or delete anything. These stay in the DoctorX app, behind a real sign-in and two-factor authentication.
Create, expire, revoke#
| Action | Where | What happens |
|---|---|---|
| Create | Settings → API & integrations → New key | The key is shown once. Each person can have up to 10 active keys. |
| Expire | Chosen when you create it (7 days to 1 year, or never) | After that date the key stops working by itself. |
| Revoke | Settings → API & integrations → Revoke | The key stops working within seconds. This can't be undone. |
| Check use | The key list | Shows when each key was last used and from which IP address. |
Clinic admins see and can revoke every key in the clinic; doctors and receptionists see their own.
Keeping keys safe#
- Server only. Call the API from your server, a serverless function or a no-code tool, never from JavaScript that runs in visitors' browsers, where anyone can read it.
- Environment variables. Store the key in a setting like
DOCTORX_API_KEYor your tool's secret store, not in the code or a Git repository. - One key per integration. Then you can revoke one without breaking the others, and the audit log shows which app did what.
- Leaked? Revoke it right away and create a new one. Check the audit log for calls you don't recognise.
Rate limits#
Each key may make 5 requests per second, with short bursts of up to 60. Going faster returns 429 Too Many Requests; wait a second and try again. That is plenty for websites, bots and syncs; see handling 429.