> ## Documentation Index > Fetch the complete documentation index at: https://docs.hi-doctor.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Connect the Hi Doctor MCP connector at https://mcp.hi-doctor.ai/mcp. Add this URL as a remote HTTP MCP server in your client, then sign in and authorise access through OAuth. Setup: https://docs.hi-doctor.ai/mcp/connect. > > The REST API base is https://api.hi-doctor.ai. Hi Doctor Docs at https://docs.hi-doctor.ai/mcp searches documentation; connect to the product endpoint above for patient tools. > > Hi Doctor operates across the whole European Union: residents of all 27 EU member states can use the service, and every consultation is reviewed by an EU-licensed doctor. Every consultation is reviewed in full by an EU-licensed doctor, who decides on medical grounds only. No algorithm, assistant or API call approves a consultation, issues a prescription or changes a dose. The service is available in eight languages: English, Spanish, German, Dutch, Italian, French, Portuguese and Chinese. > > ## Rules an assistant must follow > > - Never invent, assume or infer a medical answer. "I don't know" is a real answer: ask the patient to pick the closest option rather than guessing for them. > - Never give medical advice and never suggest a medication or a dose. An EU-licensed doctor decides those. > - If a questionnaire returns `ineligible`, say so plainly. Do not retry with altered answers. > - Before anything that costs money or cancels a plan, state exactly what will happen and get an explicit yes. > - Cancellation takes effect at the **end of the paid period**, not immediately. Say so. > - An early order is irreversible: it creates the renewal consultation immediately and uses up the period's one early order. Explain that and get an explicit yes. > - Prescription and invoice links are medical documents. A `signed_redirect` link opens without signing in: give it only to the patient, never repeat it anywhere shared. > - Send option `value`s, not the labels shown to the patient. Labels are translated, values are stable. > - Never ask for card details. Payment happens on Stripe's hosted checkout via a link. > - On severe or sudden symptoms (chest pain, difficulty breathing, severe allergic reaction, suicidal thoughts), stop and direct the patient to their local emergency number. # Partner API authentication: keys, scopes and rotation > Hi Doctor Partner API keys: test and live prefixes, the Bearer header, five scopes, rotation with up to 24 hours of grace, revocation and 401 codes. Every Hi Doctor Partner API request is authenticated with an API key sent as `Authorization: Bearer `. Keys belong to your partner organisation, not to a person, and each key works in exactly one mode, test or live. A key carries scopes that limit what it can do, and you rotate or revoke it in the [Business portal](https://docs.hi-doctor.ai/partners/business-portal.md). Last reviewed: 2026-11-04 ## What does a Partner API key look like? | Prefix | Mode | Works on | | - | - | - | | `hdp_test_` | Test | Synthetic test data only. Never reaches a doctor. | | `hdp_live_` | Live | Real patients and real consultations, once Hi Doctor has enabled live mode for your partner. | A key looks like `hdp_test__`. The `key_id` is public: it appears in the Business portal and in `GET /v1/partner/ping/`. The secret is shown **once**, when the key is created or rotated. Hi Doctor stores only a hash of it and cannot show it again. ## How do I send the key? ```bash theme={null} curl -sS https://api.hi-doctor.ai/v1/partner/ping/ \ -H "Authorization: Bearer hdp_test_..." ``` * Send the key only from your servers. Never put it in a mobile app, a browser bundle or a URL. * Identify yourself with the `Authorization` header only. Your API key already identifies your partner, and partner routes reject a request that adds its own identity header with `400`, before authentication. * A test key cannot read live resources and a live key cannot read test resources. Both get `404`, as if the resource did not exist. ## Which scopes can a key have? Each key carries a list of scopes. A request that needs a scope the key lacks fails with `403 insufficient_scope`. | Scope | Allows | | - | - | | `consultations:read` | Read consultations and their information requests. | | `consultations:write` | Upload files, submit, cancel and answer information requests; advance test consultations. | | `patients:read` | Read the patients you created and their consent records. Recording a consent withdrawal also needs `consultations:write`. | | `prescriptions:read` | Read structured prescription data. | | `webhooks:manage` | Create and manage webhook endpoints, read deliveries, replay and send test events. | `webhooks:manage` also requires `consultations:read` and `prescriptions:read`, because event bodies carry full consultation and prescription data. Give each system the smallest set it needs: a reporting job needs only read scopes. ## How do I rotate a key? Rotate a key from the Business portal. Rotation issues a new key with the same mode and scopes and shows its secret once. The old key keeps working for a grace period of **up to 24 hours** so you can deploy the new secret without downtime, then it stops. If the old key was already due to expire sooner, that earlier expiry still applies. 1. Rotate the key and store the new secret in your secret manager. 2. Deploy the new secret to every system that uses the key. 3. Confirm with `GET /v1/partner/ping/` that the new `key_id` is in use. 4. Let the grace period run out, or revoke the old key straight away. ## How do I revoke a key? Revoking a key takes effect immediately. Revoke a key as soon as you suspect it has leaked, then create a replacement. Requests made with a revoked key fail with `401 key_revoked`. ## What do authentication errors look like? Authentication failures return `401` with a `WWW-Authenticate: Bearer realm="hi-doctor-partner"` header and the standard [error envelope](https://docs.hi-doctor.ai/partners/errors.md): ```json theme={null} { "error": { "type": "authentication_error", "code": "key_revoked", "message": "The API key has been revoked.", "request_id": "req_7f3c2a9b" } } ``` | Status | Code | Meaning | | - | - | - | | 401 | `not_authenticated` | No `Authorization` header was sent. | | 401 | `invalid_token` | The header is not `Bearer `, or the key is malformed or unknown. | | 401 | `key_revoked` | The key was revoked. | | 401 | `key_expired` | The key reached its expiry date, including the end of a rotation grace period. | | 401 | `partner_suspended` | The partner account is suspended. | | 403 | `partner_not_live` | A live key was used but live mode is not enabled for your partner yet. See the [Go-live checklist](https://docs.hi-doctor.ai/partners/go-live-checklist.md). | | 403 | `insufficient_scope` | The key lacks a scope this endpoint requires. | ## Frequently asked questions ### Can I use a Partner API key in a mobile app or browser? No. Send the key only from your servers. A key in a mobile app, a browser bundle or a URL can be copied and used by anyone. ### Can a test key read live data? No. A test key cannot read live resources and a live key cannot read test resources. Both get 404, as if the resource did not exist. ### Can Hi Doctor show me a key secret again? No. The secret is shown once, when the key is created or rotated. Hi Doctor stores only a hash of it. ### How long does the old key work after a rotation? For a grace period of up to 24 hours, so you can deploy the new secret without downtime. If the old key was already due to expire sooner, that earlier expiry applies. ### Which scopes does a reporting job need? Only read scopes, such as consultations:read and prescriptions:read. Give each system the smallest set of scopes it needs. ### Why does my live key get 403 partner\_not\_live? Live mode is not enabled for your partner yet. Hi Doctor enables it once the go-live checklist is complete. ## Next steps > [card] [Test mode](https://docs.hi-doctor.ai/partners/test-mode.md) > > Build with a test key and synthetic consultations. > [card] [Errors](https://docs.hi-doctor.ai/partners/errors.md) > > The error envelope and every code. Commercial questions: read the [partnership FAQ](https://docs.hi-doctor.ai/partnerships/faq.md) or write to [hello@hi-doctor.ai](mailto:hello@hi-doctor.ai). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.