Skip to main content
The REST API authenticates with an API key sent as a Bearer token. The MCP server is OAuth-only: it accepts OAuth 2.1 tokens from AI clients that connect on behalf of a logged-in team member, and refuses API keys.

​
API keys

1

Create a key

In PracticeHub, go to Developers → API Keys, choose API key, pick the access level — Read & write, or Read only for reporting and sync integrations that never change data — optionally an expiry (90 days or 1 year), name the integration and create the key. Only a hash is stored — the key itself is shown once, so copy it now.
2

Send it as a Bearer token

The host is the one the practice signs in on, https://{clinic}.{region}.practicehub.io — the region host is the one in the practice’s login URL — neptune (London), mercury (Frankfurt), vulcan (Ohio), jupiter (Singapore) or apollo (Sydney).
Keys look like phk_… — the phk_ marker lets secret scanners (GitHub, gitleaks, truffleHog) recognise a leaked PracticeHub key. GET /me returns the integration the key belongs to, its scopes, and the account it reaches — including the timezone every date and time on the API is expressed in and the account currency. A good first call for any integration.
Each key is one integration on the account: requests are logged per integration, and audit trails record actions as that integration (for example, an appointment log reads “Created via API: Booking widget”). A read-only key can call every GET and read tool; any write returns 403 with code: key_read_only. Prefer read-only keys wherever an integration does not need to change data.

​
Rotation, expiry and audit

  • Rotate a key from Developers → API Keys → ⋯ → Rotate: you get a new secret for the same integration (same scope, same expiry date — rotation changes the secret, not the lifetime) and the previous secret keeps working for up to 24 hours so you can switch without downtime. An expired key cannot be rotated; create a new one.
  • Keys created with an expiry stop authenticating at that time (401 unauthenticated); rotate before then to get a fresh window.
  • Every key creation, rotation and revocation — and every AI-connector approval and revocation — is recorded in the account’s activity log with who did it and when.
A key gives access to the account’s data. Keep it server-side — never in a browser, mobile app or public repository. Revoke it from Developers → API Keys the moment you suspect it has leaked; revocation is immediate.

​
Which keys an account can create

​
OAuth for AI connectors

AI clients such as Claude and ChatGPT connect to the MCP server with OAuth 2.1 (dynamic client registration + PKCE). The client discovers the authorization server from the endpoint, registers itself, and the team member approves access on a PracticeHub consent screen. Actions then run as that person, with their name on the audit trail. Connecting is opt-in: account owners can always connect, other team members only if their role has Connect AI apps enabled (Settings → Security → Roles). An OAuth connector can only call the MCP server — it does not authenticate against the plain REST endpoints, which accept API keys only. See Connectors.

​
Rate limits and request IDs

Requests are limited per account, per surface (currently 120 per minute — every API key shares the account’s REST bucket, and every AI connector shares a separate MCP bucket); X-RateLimit-Limit and X-RateLimit-Remaining are returned on every response, and 429 means wait and retry. Every response carries an X-Request-Id; quote it when contacting support — the same id is shown on the account’s Developers → API Logs page.
Account-level IP restrictions (Settings → Security) do not apply to API keys or AI connectors — both are credentials the account explicitly issued, not staff sign-ins.

​
Errors