X-Brand-Slug: hi-doctor header. Keep tokens on your server, out of logs and model prompts, and never ask a patient to paste a password, code or token into a chat.
Last reviewed: 2026-11-04
The MCP connector uses its own account OAuth tokens. REST JWTs are not accepted at its /mcp endpoint, and clients must not use MCP tokens with REST. The separate HTTP chat API documents its own server-side authentication.
How does a patient sign in?
Follow sign-up and email verification first. The patient must complete verification before password sign-in works. The quickstart shows a read with securely supplied variables. For a verified password account, sendPOST /v1/users/token/ with Content-Type: application/json, X-Brand-Slug: hi-doctor and an object containing email and password. Construct JSON with your client library, never by interpolating credentials into shell commands. Do not log the request or response.
Request body
200
What do sign-in failures look like?
Password sign-in for a Google-only account returns
401; forgot-password returns 400 with the same code. Do not infer status from the code alone. See errors and recovery.
Which headers does an authenticated call need?
SendX-Brand-Slug: hi-doctor on every request, including sign-in and refresh. Unknown brands return 400 with code: "unknown_brand". The header is not a credential; it does not authenticate a business or grant access to another patient’s records.
For authenticated REST calls, send Authorization: Bearer ACCESS_TOKEN. Missing credentials return 401 with detail: "Authentication credentials were not provided.". Records outside the account’s access return 404; never probe other identifiers.
How do you refresh an expired access token?
SendPOST /v1/users/token/refresh/ with Content-Type: application/json, the brand header and a JSON refresh field containing the securely stored refresh token. Success returns a new access value.
Request body
5xx does not prove failure and must never trigger automatic write replay. See safe retries with Idempotency-Key.
Google sign-in
Hi Doctor’s Google sign-in obtains an ID token for its own Google OAuth client.POST /v1/users/google-login/ accepts a token field and can create an account. A third-party app’s Google token is not interchangeable, so this endpoint serves Hi Doctor’s own apps. Assistants should use MCP account authorisation, where sign-in happens on Hi Doctor and Google accounts work.
Frequently asked questions
How long do Hi Doctor REST tokens last?
An access token lasts one day and a refresh token 30 days. Refresh the access token with the refresh token; when refresh fails, sign the patient in again.Are refresh tokens rotated?
No. A REST refresh returns a new access token only. A password change or reset stops existing refresh tokens from working.Can I use a REST token with the MCP connector?
No. The MCP connector uses its own OAuth tokens, issued when the patient signs in on hi-doctor.ai. REST and MCP tokens are not interchangeable.Why does password sign-in fail for some accounts?
An account created with Google has no password, so password sign-in returns 401 with the Google account code. Offer Continue with Google on Hi Doctor instead.Can my app use its own Google sign-in?
No. Google sign-in over REST accepts only ID tokens issued for Hi Doctor’s own Google client, so it serves Hi Doctor’s own apps.Does the brand header authenticate my application?
No. The brand header selects the Hi Doctor brand and grants no access. Only the patient’s access token authenticates a call.Next steps
- Quickstart: Sign in and make your first authenticated read.
- Errors and recovery: Error shapes, throttles and uncertain writes.
- MCP permissions: How an AI assistant gets scoped access instead of a JWT.
- API changelog: Changes to authentication and the rest of the API.