API access

The FHIR surface, and the tokens that reach it.

Insight exposes a read-only FHIR R4 surface, so another system you work with can read the records you choose to share with it.

Before anything else

A token is a standing key to your practice's records that works without anybody signing in. Issue one only to a system you have an agreement with, and revoke it the moment that ends.

The API access screen: a warning that a token is a standing key, a field naming what the token is for, and an empty list of issued tokens

That warning is the first thing on the screen rather than fine print at the bottom, because a token is the one credential in this product that nobody has to log in to use.

Issuing a token

Settings → API access, Owner only.

The token is shown once, when it is created. It is not stored in a readable form and cannot be shown again — if it is lost, revoke it and issue another. That is also the right response to not being sure where a key to your records ended up.

Revoking takes effect immediately. Revoked tokens stay on the list rather than disappearing, so you can see what has had access and when it was withdrawn.

What the API serves

  • GET /api/fhir/r4/metadata — the capability statement, which needs no token.
  • GET /api/fhir/r4/Patient and /Patient/{id}
  • GET /api/fhir/r4/Appointment and /Appointment/{id}

Pass the token as Authorization: Bearer <token>.

It is read-only. There is no way to write into a clinical record over the API, and the capability statement says so rather than leaving an integrator to discover it.

What it will never serve

  • Restricted clients, and their appointments.
  • Psychotherapy notes, categorically.
  • Any clinical content at all — no chart, no diagnosis, no measure. An appointment carries who and when, never what was discussed.

Every read is recorded in your audit log, including requests for records that do not exist, so a later review can see exactly what a token was used for.

Before you give one out

A token is a disclosure of PHI to a third party, and the paperwork is not optional: the receiving organisation needs a Business Associate Agreement in place before the token is issued, not after the integration is working.

If the integration is for something outside treatment, payment or operations, that is an authorisation question as well as a BAA one.

When it goes wrong

401 on every request. The token is wrong, revoked, or being sent as something other than Authorization: Bearer <token>. Try /metadata first — it needs no token, so a working /metadata and a failing /Patient isolates it to the token.

A patient you can see is not there. They are restricted. Restricted clients and their appointments are never served, and no token setting changes that.

An appointment has no clinical detail on it. By design. An appointment carries who and when; what was discussed is not on the API at all.

You lost the token. It cannot be shown again — it is not stored in a readable form. Revoke it and issue another. Do the same whenever you are not certain where a key to your records ended up.

A former integrator still appears on the list. Revoked tokens stay listed rather than disappearing, so the history of who had access survives the revocation. Check the revoked date rather than the presence of the row.