Scopes & permissions

Every capability your app has is expressed as a SMART v2 scope, and every scope your app can request comes from its permission schema — a versioned, reviewable list you manage in the portal.

The grammar

<context>/<ResourceType>.<interactions>

• patient/ — confined to the patient chart your app was launched from. patient/Condition.rs reads and searches only the launched patient's conditions.
• user/ — follows the signed-in clinician's own access. user/Appointment.rs sees the clinician's schedule across patients.
• Interaction letters are SMART v2 granular: c create, r read, s search. .rs means read + search; .c means create-only.

Protocol scopes sit alongside resource scopes:

• launch — required for every app; the portal adds it automatically.
• openid — requests an OpenID Connect id_token identifying the user.
• fhirUser — adds a claim pointing at the user's FHIR resource. Requires openid.
• launch/servicerequest — asks for a ServiceRequest id in launch context when the launch originates from an order.

Wildcards (patient/*.read), free-form scopes, and anything not in the capability catalog are rejected — at schema save time in the portal, and again at authorization time by the EMR.

Permission schemas

A schema is an immutable, numbered version of your app's requested scopes. Each scope carries a written rationale; clinicians see those rationales on the authorization screen, so write them for the person deciding whether to trust your app ("Show the launched patient's active medications", not "med access").

Editing permissions creates a new draft version; deployed versions never change underneath a clinic. When a new version only narrows access, existing consents stand. When it broadens access — any new (context, resource, interaction) atom — users are asked to re-consent on their next launch, so batch scope additions deliberately rather than dripping them out.

Requesting less at runtime

Your authorization request may ask for any subset of the deployed schema. The granted scope in the token response is authoritative and may be narrower than requested — always read it back rather than assuming.

What's requestable

The selectable catalog is exactly what the sandbox EMR advertises — see the API reference for the per-resource scope tables. The sharp edges people hit:

• Observation has no launch scopes at all (Backend Services only).
• ServiceRequest is user/ServiceRequest.r — read-only, no search.
• DocumentReference and Media are create-only (.c).
• system/ (Backend Services) scopes exist in the EMR but are not yet registrable through this portal.