Entitlements
Which endpoints your API key can call, how access is granted, and what a 403 with requiredFeature means.
Every back-office endpoint is gated on your workspace's plan, one entitlement per operation. Reading a patient roster and reading a single patient are separate grants; so are reading a prescription and writing one.
This is not a scope you set on the key. It is granted on the medos side, per workspace, and takes effect without you changing anything.
The booking endpoints are not gated
Everything documented under Appointments, QMS, Session packs and OTP works on any active key, exactly as before. Gating applies to the back-office surface: patient lookup and roster, appointment read-back, master data, and clinical records.
When you are not entitled
{
"success": false,
"message": "This workspace's plan does not include devapi_patients_list. Contact your medos administrator to enable it.",
"requiredFeature": "devapi_patients_list"
}Status is 403. Branch on requiredFeature rather than on the message — the
message is for a human reading a log, the code is stable.
A 403 here means this workspace has not been granted this operation. It does
not mean your key is wrong, your IP is unlisted, or the record does not exist.
Those are different failures:
| Status | Body clue | What it is |
|---|---|---|
401 | Invalid API key | The key is unknown, inactive or expired. |
403 | requiredFeature | Not entitled. Ask your medos administrator. |
403 | not allowed from <address> | The key is valid, the caller's IP is not on its allowlist. |
403 | only available to Developer API keys | A session token was used on a server-only endpoint. |
404 | upstream body | Entitled, authenticated — the record is not there. |
Getting an operation enabled
Ask whoever administers your medos plan. They grant it per workspace, so enabling patient lookup for you does not enable it for every clinic on the same plan.
Two things worth knowing about the timing:
- A grant reaches the API within about ten minutes. There is a cache, so a change is
not instant — but it never needs a deploy, and if you are testing a grant and still
seeing
403, waiting is usually the answer. - A workspace with no active subscription behaves as if nothing is enabled. If
every back-office call starts answering
403at once, check the subscription before checking the grants.
Entitlement names
Codes read devapi_<area>_<operation>. You do not need to construct them — a
403 tells you exactly which one you are missing — but the grouping is useful
when asking for access:
| Area | Covers |
|---|---|
devapi_appointments_* | Appointment read-back: by id, filtered search, schedule slots |
devapi_qms_* | Queue visits, day visits, shift status |
devapi_patients_lookup_* | Finding a patient by MRN, email or phone |
devapi_patients_get, devapi_patients_visits | One patient, and their visit history |
devapi_patients_list | The full workspace roster |
devapi_patients_upsert | Creating and updating patient records |
devapi_catalog_* | Locations, rooms, practitioners, scheduling configuration |
devapi_prescriptions_* | Prescriptions, including the rendered PDF |
devapi_patients_vitals_*, devapi_patients_medical_history_create | Clinical writes against a patient |
devapi_medicines_search | Medicine catalogue lookup |
The roster is granted separately, on purpose
devapi_patients_list returns every patient in the workspace. It is a
deliberately separate grant from looking one up by MRN, because the two carry
very different risk. Expect it to be refused even where lookup is allowed.
Rate limits are a different thing
Entitlement says whether you may call an endpoint. Rate limits say how often.
They are enforced independently, so being entitled does not exempt you from the
per-key and per-route budgets — see
authentication. A 429 is never an
entitlement problem.