Mantys Eligibility APIAuthentication
Three headers on every authenticated request: what each one identifies, and what a rejection looks like.
Every endpoint except /health takes the same three
headers. There is no OAuth flow, no token exchange and no refresh: the API key
is long-lived and issued to you directly.
To get a key, a clinic id and a client id, contact kriti@mantys.io or sudhanshu@mantys.io.
The headers
| Header | Example | What it identifies |
|---|---|---|
x-api-key | Bearer api_yourclinic_c3a9… | Your integration. The literal word Bearer, a space, then the key. |
X-Clinic-ID | 00000000-0000-4000-a000-0000000000c1 | The clinic the check is being run for. Must be a clinic your key owns. |
X-Client-ID | yourorg | Your organisation. Every task you create is recorded against it. |
The Bearer prefix is not optional
x-api-key is compared against the string Bearer <key>, not against the key
alone. Sending the bare key returns 401 with Invalid API key format.
Header names are matched case-insensitively, so X-Api-Key and x-clinic-id
work too. This site writes them the way the backend does.
Why three
The key authenticates you. X-Clinic-ID scopes the request to one clinic,
which is also how results are partitioned: a task created under one clinic id
is invisible to an eligibility-result call made with another. X-Client-ID
identifies your organisation; a wrong value is rejected with a 401 rather than
returning another organisation's data.
One key may own several clinics. Send the clinic the patient is actually being seen at: it selects the payer credentials the check runs under.
What a rejection looks like
| Code | detail | Cause |
|---|---|---|
| 401 | Invalid API key | x-api-key missing, or not a key we know. |
| 401 | Invalid API key format | Key sent without the Bearer prefix. |
| 401 | Invalid clinic ID | X-Clinic-ID missing, or not a clinic on the platform. |
| 401 | Clinic ID not authorized for this API key | Real key, real clinic, but the key does not own that clinic. |
| 404 | Task not found | The task id exists but belongs to a different clinic, or does not exist at all. Deliberately indistinguishable. |
Sample not captured yet
create-task/error-401 will be filled in once the sample capture pass has run against a completed production task.Sample not captured yet
create-task/error-401-clinic-not-owned will be filled in once the sample capture pass has run against a completed production task.Authentication failures are always 401
The API does not return 403. Ownership failures, an unrecognised key and a missing header all come back as 401, so a single 401 branch covers every credential problem. Do not fold 400 or 422 into it: those mean the request itself was wrong, not the credentials. See Errors.
Keeping the key safe
The key is equivalent to a login for every clinic it owns, and the data behind it is patient health information. Keep it in your secret store, send it only over TLS, and never put it in a URL, a query string, a client-side bundle or a log line. If you think a key has leaked, email kriti@mantys.io or sudhanshu@mantys.io to have it rotated. Rotation is immediate and old keys stop working at once.