Developer API overview
Call Medos directly from your own backend with a secret API key, locked to your servers' addresses.
The widgets in this documentation run in a browser and book on a patient's behalf. The server-side API is the other half: your backend calling Medos directly, so you can drive bookings, patients and packages from your own system.
Which one do you want?
| Widget | Server-side API | |
|---|---|---|
| Runs in | Your visitor's browser | Your server |
| Credential | Publishable mk_ key | Secret mk_ key, sent as x-api-key |
| Is the key a secret? | No — it is public by design | Yes — treat it like a password |
| Locked to | Your website's domain | Your servers' IP addresses |
| Good for | Booking flows on your website | Syncing your own CRM, EMR or admin tooling |
They are not exclusive. Most clinics embed a widget for patients and use the server-side API for back-office work.
Keys come in three types, and the dashboard asks which you want at creation: SDK widget for the browser, Developer API for your backend, and Internal for Medos first-party services, which is not issued to customers. This section is about Developer API keys. A Developer API key will not work in a browser and is not meant to — for that you want an SDK widget key.
The trust model
Your API key is the credential. Your IP allowlist is what keeps a copy of it useless.
There is nothing to sign and no keypair to manage: every request carries the API key, and Medos checks it. That makes the key a real secret — anyone who has it can call the API as you — so two things matter:
Keep the key on your server. In a secret manager or an environment variable, never in a browser, a mobile app, or a code repository. It is shown in full once, when you create it.
Register the addresses your servers call from. A request from any other address is refused, even with the right key. That is what stops a key copied out of a log, a leaked config file or a screenshot from being used by anyone else.
The allowlist is doing real work
With no signature involved, the allowlist is the second factor. Register the narrowest addresses you can — your NAT gateway's address rather than your cloud provider's whole range — and rotate the key if it is ever exposed. See IP allowlist.
What every request carries
| What it is | What it does | |
|---|---|---|
x-api-key | Your API key | Identifies your key, and authenticates the request |
| Your source IP | Where the request came from | Must be on the key's allowlist |
x-end-user-id | A stable id for one patient | Only on OTP and 🔒 routes — keeps each patient's verification separate |
The last one exists because one API key serves every patient you have. When a patient verifies their phone, that verification has to belong to that patient, not to your whole integration. See OTP-gated routes.
How a request travels
Your server calls the Medos gateway with its API key. The gateway checks the key, checks your address, works out which workspace the key belongs to, and then talks to the Medos core on your behalf.
your backend ──[x-api-key]──> Medos gateway ──> Medos core
│
├── checks the key is live
├── checks your source IP
└── binds the request to the key's workspaceTwo properties fall out of that shape:
- The workspace is decided by the key, not by your request. Every route is scoped to the workspace the key is registered against, so nothing you send can reach another tenant's data.
- You reach the documented endpoints and nothing else. Each route is opened to
API keys individually, and anything else answers
403— including routes the widget uses. Nothing is forwarded through to the Medos core. See Endpoints.