# Healthcare API with patient consent

> How access to a record is granted by the patient through OAuth 2.1 scopes and durations, logged and revocable, what it changes in an application's design, and how pairwise ids keep applications apart.

Source: https://developers.anpheros.com/guides/healthcare-api-patient-consent

**A healthcare API with patient consent is one where access to a record is granted by the patient, for a purpose, for a time, and can be seen and withdrawn by the patient, rather than decided once by the organisation that holds the data.** In Anpheros, consent is not a field you set; it is the mechanism through which an application reaches a record at all. This guide explains how that works for a developer and what it changes in an application's design.

## Two ways to reach a record

| | Organisation access | Patient-granted access |
|---|---|---|
| Who authorises | your organisation, through an API key | the patient, through an OAuth 2.1 consent screen |
| Typical use | a clinic or laboratory writing results, your own app writing on behalf of its users | a third-party app, an AI assistant, a doctor's tool, a family member |
| Scope | the patients your organisation created or that were shared with it | the scopes the patient accepted (`patient/Observation.read`, …) |
| Duration | while the key is valid | the duration the patient chose; renewable, revocable |
| Visible to the patient | yes, in the access log | yes, with the ability to withdraw |

Both paths go through the same API and the same FHIR record. The difference is who holds the key to the door.

## The consent flow, step by step

1. Your application sends the patient to the Anpheros authorisation endpoint with the scopes it needs and a reason in plain language.
2. The patient sees what you ask for, chooses a duration and accepts or declines. The screen is in the patient's language.
3. You receive an access token limited to those scopes and that patient. Tokens are short-lived; refresh tokens last as long as the consent.
4. Every read and write with that token is logged with your application's name. The patient sees the log in their app.
5. If the patient withdraws consent, the next request fails with a clear error. You receive a webhook so you can clean up.

The flow is standard OAuth 2.1 with PKCE and SMART on FHIR scopes, so existing libraries work. The [Authentication and OAuth](https://developers.anpheros.com/guides/authentication) guide has the exact parameters and the [Consent and access model](https://developers.anpheros.com/guides/consent) the rules behind it.

## What it changes in your application

- **You ask for less.** Scopes are per resource type and per direction. An app that charts weight asks for `Observation.read`, not the whole record.
- **You design for withdrawal.** Access can end at any time. Cache little, re-read when needed, and handle the revoked error as a normal state.
- **You get trust for free.** Patients see your application's name, what it can reach and when it last read something. Applications that behave well are easier to accept.
- **You write with provenance.** Everything you write carries your application as author and, when relevant, the person on whose behalf. The patient and other applications can tell your data from theirs.

## Identifiers that do not leak

Each application sees a patient under a pairwise identifier: the same person has a different id in your application and in another one. Two applications cannot join their data about a person without the patient's consent, even if both are built on Anpheros. For your code this is invisible; for the patient it is the difference between consent and a formality.

## Families and carers

Consent extends to people who manage records for others: a parent for a child, an adult child for an elderly parent. The record stays with the account that created it; other accounts receive access, which can be withdrawn. Your application sees the same consent mechanism, with the carer as the person who accepts.

## Related

- [Consent and access model](https://developers.anpheros.com/guides/consent)
- [Authentication and OAuth](https://developers.anpheros.com/guides/authentication)
- [SMART on FHIR backend](https://developers.anpheros.com/guides/smart-on-fhir-backend)
- [Healthcare API](https://developers.anpheros.com/guides/healthcare-api)
- [Security, privacy and data residency](https://developers.anpheros.com/guides/security)