Troubleshooting & FAQ

The key didn't reach us or isn't valid. Check that the header is exactly Authorization: Bearer hfk_… (one space after Bearer, no quotes around the key), that you copied the whole key, and that it isn't expired or revoked in Settings → API & integrations. Keys only work in the header, not in the URL.

The key is fine but wasn't given the scope this endpoint needs. The endpoint's scope is shown in the reference. Scopes can't be added to an existing key: create a new key with the right scopes and revoke the old one.

That endpoint isn't available to API keys at all, on purpose (for example deleting records, staff management or exports). Do it in the DoctorX app.

Only doctors and clinic admins can read clinical records, in the app and through keys. Ask one of them to create the key.

One or more fields are wrong. The response's error.fields names each one with the reason, e.g. {"gender": "is required"}. Unknown field names are rejected too, so check for typos.

The doctor already has an appointment overlapping that time, or you asked for an impossible status change (like completed → scheduled). Pick another time or check the current status first.

More than 5 requests a second (bursts to 60) from one key. Slow down and retry after a second; see the retry helper. For big syncs use limit=100 pages instead of many small calls.

The clinic's plan has lapsed or the clinic is read-only. Renew under Settings → Plan & billing; writing resumes immediately.

DoctorX returns times in UTC (ending in Z). Convert to the clinic's time zone before showing them, and send times with an offset like +05:30.

Browsers block calls to other sites (CORS), and that's a good thing: putting the key in browser code would expose it to every visitor. Call DoctorX from your server or a serverless function instead.

Check the MCP config is valid JSON, that the URL ends in /api/mcp, and restart the assistant fully. Claude Desktop also needs Node.js installed. Tools only appear for the scopes the key has.

No. Deactivating a user, or signing them out of all devices, disables their keys at once. Admins can also revoke any key in the clinic.

Use a trial clinic (sign up with another email) for experiments, so test patients don't mix with real ones.