Skip to main content
This page answers the questions a security or procurement review asks about integrating with the PracticeHub API. Every statement here describes how the platform is built today; where something is a policy rather than a mechanism, it says so. For questionnaires that need more, contact us and we’ll answer from the same source.

​
Tenancy and data residency

  • One database per account. Each clinic account is a tenant with its own database. The account is identified from the request host ({clinic}.{region}.practicehub.io — the practice’s own login host, in its region), and a credential is bound to the account it was issued on: it is refused anywhere else.
  • Five regions. Accounts are hosted in London, Frankfurt, Ohio, Singapore or Sydney, and the API for an account is served from that account’s region. Webhook events (record ids only — see below) are delivered from a regional environment: EU for London and Frankfurt accounts, US for Ohio, Singapore and Sydney.
  • Credentials are account-bound. API keys belong to an integration record on the account; OAuth connector tokens belong to a team member on the account. Neither authenticates against another account.

​
Authentication and credentials

  • Format phk_…; the prefix lets secret scanners recognise a leaked key.
  • Only a SHA-256 hash is stored; the plain key is shown once at creation and cannot be retrieved afterwards.
  • Scoped: read & write, or read-only. A read-only key is refused on every write path — enforced once, in the write service, not per endpoint.
  • Optional expiry (90 days / 1 year) and rotation with a 24-hour grace period for the old key. Revocation is immediate.
  • Created, rotated and revoked only by signed-in team members with the developer permission, from Developers → API Keys; every one of those actions is written to the account’s activity log.
  • OAuth 2.1 with PKCE, dynamic client registration with an allow-list of redirect hosts, and per-account consent screens shown to the signed-in team member.
  • Access tokens live 1 hour; refresh tokens 30 days and rotate on use.
  • Opt-in per role: a team member can only connect an AI app if their role has Connect AI apps enabled by an administrator.
  • Acts as the person, with their role: a connector can only read, write or delete what the team member’s PracticeHub role allows, including own-patients / own-calendar ringfencing.
  • Cut-off on every call: a deactivated team member, or one whose role loses the permission, is refused on the next request — not at the next token refresh.
  • Connections are visible and revocable in-app (Developers → API Keys → Connected AI apps); each authorisation and revocation is in the activity log.

​
Transport and abuse controls

  • HTTPS is required for every API call and every webhook endpoint.
  • Rate limits per account (currently 120 requests/minute per surface — every API key shares the account’s REST bucket, every AI connector a separate MCP bucket), with X-RateLimit-* headers and Retry-After on 429, so no client can drive unbounded load at an account’s data.
  • Every response carries an X-Request-Id; quote it to support and it can be traced end to end.
  • Idempotency-Key on POST guarantees a retried create is not applied twice.

​
Logging and what is stored about your calls

  • The account’s Developers → API Logs page is a filterable report of every API request: time, calling key or connector user, method, path, resource and record id, query-parameter names, status, the API’s error code and message, latency, response size, idempotent-replay flag, IP and user agent, request id — with usage, error and latency summaries and CSV export.
  • Those log rows are PHI-free by construction: no request or response bodies are stored, query-parameter values are never stored, and the only free text kept is the API’s own error message (generic wording that never echoes submitted values).
  • Log rows are retained for 90 days, then pruned automatically.
  • Data changes made through the API are attributed in the record’s own history to the integration or team member that made them (for example an appointment log entry “Created via API: Booking widget”).

​
Webhooks

Live in a limited rollout — patient and appointment events first; see Webhooks.
  • Payloads are thin: event type, event id, timestamp, and the entity type + record id — no field values, so no PHI transits the delivery provider. Consumers fetch the record over the authenticated API.
  • Every delivery is signed (Standard Webhooks); endpoints, signing secrets, delivery attempts and replays are managed by the account in its own portal.
  • Use HTTPS endpoints.

​
Files

Files uploaded through the API are stored in PracticeHub’s object storage and served only via short-lived signed URLs to authenticated callers.

​
Change management

  • Additive only within the current version: new resources, attributes, event types and optional inputs may appear; nothing is renamed, removed or made required. Anything else arrives as a new version with a published deprecation window.
  • The OpenAPI document is produced from the API itself and checked for accuracy and breaking changes before release.
  • Every contract change is dated in the changelog.

​
Your responsibilities

  • Treat API keys as secrets: server-side only, never in client-side code, rotate on staff change, use read-only keys where writes aren’t needed.
  • Verify webhook signatures before acting on a delivery.
  • Use the least scope and the shortest key expiry that fits the integration.
  • Data you fetch is your account’s patient data; handle and retain it under your own obligations to the clinic.
Certifications, penetration-test summaries, sub-processor lists and data-processing agreements are provided on request as part of contracting — help@practicehub.io.