Authentication & scopes
Every request to the iClinic Integration API needs an API key in the Authorization header, using the Bearer scheme. The API uses no cookies and no OAuth; a valid key is all you need.
- No automatic expiry. A key works until a clinic admin revokes it.
- Read-only. A key cannot change or delete data.
- Limited by scope. Each key reads only the types of data the clinic admin chose when creating the key (see the table in the Scopes section).
- Limited to one clinic. Each key sees only the data of the clinic that created it. A clinic can have at most 10 active keys at the same time.
- Only a fingerprint is stored. iClinic keeps only the sha256 hash of a key, so it cannot show the key again. If you lose a key, create a new one; the old key cannot be recovered.
Treat a key like a password. Keep it in an environment variable or a secret store. Do not put it in source code or in code that runs in your customers' browsers. If you suspect a key has leaked, create a new key, update your system, then revoke the old key with Thu hồi (Revoke). Revoking takes effect immediately.
Scopes
A clinic admin chooses the scopes when creating a key; no scope is selected by default. A request to a path outside the key's scopes returns 403 INSUFFICIENT_SCOPE. The response is identical whether or not the record exists.
| Scope | Can read |
|---|---|
encounters:read | /encounters |
patients:read | /patients, /patients/{id} |
appointments:read | /appointments, /appointments/{id} |
receipts:read | /receipts, /receipts/{id} |
therapy:read | /therapy-plans, /therapy-plans/{id} |
A key created before version 1.1.0 has only encounters:read, exactly as before.
Request only the scopes you need. Patients, appointments, receipts and therapy plans are personal data, and part of it is health data. Use them only for the purpose the patient agreed to, and revoke a key when you no longer use it.
Rotate a key without interrupting your service
Create a new key, update your system, then revoke the old key. During the switch, both keys keep working at the same time.
Authorization: Bearer ick_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx