SMART on FHIR scopes explained: patient, user and system

SMART on FHIR scopes are space separated strings that state what an app wants to access. A scope has a prefix (patient, user or system), a resource type, and permission letters from c, r, u, d and s. Ask for the narrowest set your app needs, then check what the server actually granted.

Anatomy of a scope

Take patient/Observation.rs.

• Prefix: patient/ limits access to resources tied to the patient in context.
• Resource: Observation is the FHIR resource name. Names are case sensitive.
• Permissions: rs means read and search.

The prefix user/ covers anything the logged in user can reach, which may span many patients. The prefix system/ is for direct, non user access, such as a background service.

The permission letters

They follow a dot after the resource and must appear in this order: c, r, u, d, s.

• c: create
• r: read, including version read and history of a single resource
• u: update or patch
• d: delete
• s: search

So .cu is valid and .uc is not. Write access does not imply read access. An app that creates observations and also reads them needs create and read plus search, such as .c and .rs.

Launch and context scopes

• launch says the app started from inside the EHR and should receive the session context.
• launch/patient asks for a patient to be selected, which standalone apps need because they start without context.

Identity and refresh scopes

• openid asks for an ID token, and fhirUser adds a claim naming the user as a FHIR resource such as Practitioner or Patient. Validate the token signature with the issuer's published keys.
• offline_access requests a refresh token that can work after the user goes offline. online_access works only while the user remains online.

Security habits

1. Avoid wildcard resource scopes. The star matches every type, including ones added later.
2. Prefer patient/ over user/ when the app serves one patient at a time.
3. Request offline access only if you truly need background refresh.
4. Compare the granted scope list in the token response with what you asked for. Servers may grant less.
5. Treat system scopes as high value credentials and rotate them.

For the bigger picture, read FHIR security is not built in.

Quick check

Sources

• SMART App Launch: Scopes and launch context (HL7)

Last reviewed: 19 October 2026.