SMART on FHIR for AI apps: an authorisation checklist for clinical data access

Why it matters more for AI

Traditional SMART apps show data to a clinician who is already authorised to see it. AI apps often do more: summarise a whole record, draft notes back into the chart, or run in the background across many patients. That widens both the data an app touches and the consequences of a misconfigured scope. In the US, HTI-1 also moved certified health IT from SMART v1 to the SMART App Launch 2.0 guide for the standardised patient and population API criterion, so v2 behaviour is now the baseline buyers expect⁶. The policy side is covered in HTI-1 to HTI-5.

1. Scopes: ask for the least, precisely

• Use v2 scope syntax. Permissions are expressed as suffixes from c, r, u, d and s. patient/Observation.rs grants read and search on the patient's observations; patient/Observation.cu grants create and update¹.
• Narrow with search parameters. v2 allows granular scopes such as Observation access limited to the vital-signs category¹⁵. A sepsis model that only needs vitals and labs shouldn't hold a token for psychotherapy notes.
• Prefer patient/ over user/ and system/ wherever the use case is about one patient in context.
• Separate read and write. If the AI drafts notes, consider a distinct, reviewable write path rather than giving the summariser create rights.
• Check what the server actually supports. Servers advertise capabilities in their SMART configuration⁵; don't assume granular scopes are enforced everywhere.

2. Launch and token handling

• PKCE with S256, always. The specification says all SMART apps shall support PKCE, servers shall support S256 and shall not support the plain method².
• Use EHR launch for in-workflow AI, so the patient and encounter come from the EHR's launch context, not from parameters the app constructs¹².
• Request openid fhirUser so every AI action can be attributed to an identified user².
• Keep tokens out of the model. Access tokens belong in the integration layer, never in prompts, logs or tool arguments the model can see or echo.
• Be deliberate about offline access. Refresh tokens extend reach well beyond the clinician's session; request them only when the use case needs it.

3. Background and population workloads

• Use SMART Backend Services for autonomous processing, such as overnight risk scoring or quality measures. It is designed for clients with pre-authorised scopes and no user in the loop³.
• Authenticate with asymmetric keys. private_key_jwt is the specification's preferred method because no shared secret crosses the wire; clients must support RS384 and ES384⁴.
• Rotate keys through a JWKS endpoint, and treat the private key with the same controls as any production secret.
• Use bulk export for volume, as in FHIR bulk data pipelines, rather than looping single-patient queries.

4. Agents and tools

• One tool, one scope set. If an agent reaches FHIR through MCP servers, each server should hold the narrowest token for its job, with the controls in securing MCP servers.
• Keep patient context fixed. An agent must not be able to switch patients by changing a tool argument; patient identity comes from the launch, not the prompt. This is a key defence against prompt injection.
• Human approval for writes. Drafted notes, orders or messages go to a clinician for review before they are committed, as in ambient scribe architectures.

5. Evidence for the security review

• A table of every scope requested, why, and which feature uses it.
• Audit logs linking each FHIR call to user, patient, feature and model version.
• Token lifetimes, refresh policy and revocation procedure.
• Results of testing with a SMART conformance tool against the target servers.
• A data flow showing exactly where PHI goes, including any model provider, mapped to HIPAA Security Rule controls.

How I can help

I design EHR integrations for AI products that pass hospital security reviews the first time, from scope design to agent tooling and audit. See healthcare data architecture, or analyse your challenge and bring the result to a call.