Partner API authentication: keys, scopes and rotation

Every Hi Doctor Partner API request is authenticated with an API key sent as Authorization: Bearer <key>. 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. 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_<key_id>_<secret>. 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?

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.

Rotate the key and store the new secret in your secret manager.
Deploy the new secret to every system that uses the key.
Confirm with GET /v1/partner/ping/ that the new key_id is in use.
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:

{
  "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 <key>`, 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.
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

Test mode

Build with a test key and synthetic consultations.

Errors

The error envelope and every code.

Commercial questions: read the partnership FAQ or write to hello@hi-doctor.ai.

Start

Build

Operate

Partner API reference

Partner API authentication: keys, scopes and rotation

What does a Partner API key look like?

How do I send the key?

Which scopes can a key have?

How do I rotate a key?

How do I revoke a key?

What do authentication errors look like?

Frequently asked questions

Can I use a Partner API key in a mobile app or browser?

Can a test key read live data?

Can Hi Doctor show me a key secret again?

How long does the old key work after a rotation?

Which scopes does a reporting job need?

Why does my live key get 403 partner_not_live?

Next steps

Test mode

Errors

​What does a Partner API key look like?

​How do I send the key?

​Which scopes can a key have?

​How do I rotate a key?

​How do I revoke a key?

​What do authentication errors look like?

​Frequently asked questions

​Can I use a Partner API key in a mobile app or browser?

​Can a test key read live data?

​Can Hi Doctor show me a key secret again?

​How long does the old key work after a rotation?

​Which scopes does a reporting job need?

​Why does my live key get 403 partner_not_live?

​Next steps

Test mode

Errors

What does a Partner API key look like?

How do I send the key?

Which scopes can a key have?

How do I rotate a key?

How do I revoke a key?

What do authentication errors look like?

Frequently asked questions

Can I use a Partner API key in a mobile app or browser?

Can a test key read live data?

Can Hi Doctor show me a key secret again?

How long does the old key work after a rotation?

Which scopes does a reporting job need?

Why does my live key get 403 partner_not_live?

Next steps