openEHR logo

SMART on openEHR (SMART)

Issuer: openEHR Specification Program

Release: ITS-REST development

Status: DEVELOPMENT

Revision: [latest_issue]

Date: [latest_issue_date]

Keywords: JSON, REST, SMART, OAuth2, OIDC, Authentication, Authorization, Application, App
openEHR components
© 2023 - 2025 The openEHR Foundation

The openEHR Foundation is an independent, non-profit foundation, facilitating the sharing of health records by consumers and clinicians via open specifications, clinical models and open platform implementations.

Licence

image Creative Commons Attribution-NoDerivs 3.0 Unported. https://creativecommons.org/licenses/by-nd/3.0/

Support

Issues: Problem Reports
Web: specifications.openEHR.org

Amendment Record

Issue Details Raiser Completed

ITS_REST Release (unreleased)

1.1.0

Reworded and structurally improved multiple sections of the specification for clarity, consistency, and technical accuracy; introduced a consolidated section for the experimental features.

S Iancu

20 May 2025

1.0.0

SPECITS-69. Adding "SMART on openEHR" specifications.

S Ramesh,
S Iancu

09 Sep 2023

Acknowledgements

Primary Author

  • Sidharth Ramesh; Medblocks.

  • Sebastian Iancu; Architect, Code24, Netherlands

Contributors

This specification has benefited from formal and informal input from the openEHR and wider health informatics community. The openEHR Foundation would like to recognise the following for their contributions.

  • Ian McNicoll MD, FreshEHR, UK

  • Bostjan Lah, Senior Architect, Better, Slovenia

A significant part of the design ideas of this specification was derived from:

  • SMART App Launch - Release 2.1.0, published by HL7® FHIR® standard

Trademarks

  • 'openEHR' is a registered trademark of the openEHR Foundation

  • HL7® and FHIR® are the registered trademark of the Health Level Seven International and their use does not constitute endorsement by HL7

  • SMART™ and the SMART logos are trademarks of The Children’s Medical Center Corporation. Used with permission.

1. Preface

1.1. Purpose

This document describes the SMART framework for an openEHR enabled platform.

The intended audience includes:

  • EHR systems, Platform or Application vendors;

  • Standards bodies producing health informatics standards;

  • Solution vendors.

1.2. Related Documents

Prerequisite documents for reading this document include:

1.3. Status

This specification is in the DEVELOPMENT state. The development version of this document can be found at https://specifications.openehr.org/releases/ITS-REST/latest/smart_app_launch.html.

Known omissions or questions are indicated in the text with a 'to be determined' paragraph, as follows:

TBD: (example To Be Determined paragraph)

1.4. Feedback

Feedback may be provided on the openEHR ITS forum.

Issues may be raised on the specifications Problem Report tracker.

To see changes made due to previously reported issues, see the ITS-REST component Change Request tracker.

2. Overview

2.1. Background

SMART stands for “Substitutable Medical Applications and Reusable Technologies”, a healthcare standard enabling applications to access clinical information from a data store. It was originally proposed by the SMART Health IT project (run by the Computational Health Informatics Program at Boston Children’s Hospital) and later formalized as SMART App Launch Framework, layered on top of the FHIR APIs to facilitate standardized data access.

The specification builds on OAuth 2.0 and OpenID Connect (OIDC), widely adopted industry standards for authentication and authorization. It allows third-party applications to authenticate and interoperate securely with any compliant system. It also defines launch sequences, token scopes, context passing mechanisms, and FHIR-based data access norms.

2.2. Glossary

Term Definition

SMART on openEHR

This specification document detailing the SMART framework for an openEHR enabled platform

SMART App Launch

The original SMART framework specified by HL7 FHIR, often referred as "SMART on FHIR"

Vendor

An entity that develops and supplies software to end-users.

User

The individual operating the Application to perform specific functions; also referred to as the "end-user".

Application

A software application developed by a Vendor to operate with a Platform and/or Launcher, potentially built by the same or a different Vendor. In OAuth terminology this is the "client", whereas in FHIR is often called the "SMART App".

Platform

A software ecosystem comprising at minimum an Authorization Server, an openEHR Clinical Data Repository (CDR), and a FHIR Server. It exposes openEHR REST APIs, FHIR APIs, and possibly other APIs. In FHIR this is often referred to as the "EHR system". The Platform includes the authentication and authorization infrastructure that supports OAuth 2.0 Framework and this specification.

Launcher

A user-facing application, typically developed by the Platform vendor, which initiates the launch of Applications within the context of a specific Patient or Practitioner. The Launcher may be integrated into the Platform’s main application (e.g. as a Portal) or exist as an independent application.

EHR

A (session) context representing the openEHR EHR container for the corresponding Patient, indicating the subject of interactions through the Application.
Note

The SMART App Launch Framework specification uses the terms 'EHR' and 'EHR system' to describe a system comprising a FHIR Server, Authorization Server, and potentially other components, including a Launcher.

In contrast, openEHR defines an EHR Information Model, centered around the root EHR container.

To avoid ambiguity, this specification reserves the term 'EHR' exclusively for references to openEHR constructs (e.g., EHR type, EHR ID). Alternate terminology will be used to describe equivalent FHIR-based system components.

2.3. Why SMART on openEHR?

A widely accepted vision today is that no single software vendor can provide all the necessary tools and solutions required by a modern healthcare system, while simultaneously ensuring high quality and maintaining a low total cost of ownership. Independent vendors, specializing in solving specific problems, often offer advantages over monolithic software suites attempting to address all needs.

In practice, this vision necessitates a collaborative ecosystem where applications from multiple vendors operate together to deliver a comprehensive solution. This approach is often referred to as a "best-of-breed" architecture. However, current implementations typically involve a lengthy and complex manual "integration" phase, during which vendors must coordinate their systems to interoperate, an expensive and time-consuming process that poses a significant barrier to entry for new vendors.

The SMART specification addresses this challenge by standardizing the security and interactions between systems and applications. It establishes a clear contract between the Application Vendor and the Platform Vendor, covering the following requirements:

  • The Application must be able to run on a domain owned by the Application Vendor.

  • The Platform must be able to operate on a domain owned by the Platform Vendor.

  • The Application must be able to discover the API services provided by the Platform.

  • The Application must be able to authenticate with the Platform to access its APIs.

  • The Platform must be able to authorize the Application for specific actions and data access, based on user roles and granted scopes.

  • The Application must be able to determine the active operational "context" managed by the Platform, such as the current EHR.

  • The Application must be able to embed within the Platform's user interface while maintaining the current context to ensure a seamless user experience.

The SMART on openEHR specification is designed to maintain compatibility with SMART App Launch Framework, while extending it to work with openEHR REST APIs and potentially other API types. It defines a framework supporting the following capabilities:

2.4. Foundational Concepts

The openEHR Reference Model and the openEHR REST API specification provide the foundational structure for interoperable Applications. For these applications to be truly portable across systems and vendors, a standardized approach to authentication and authorization is essential.

Authentication is the process of verifying the identity of an end-user or client application, while Authorization is the process of determining what access or privileges that entity has.

The SMART on openEHR specification builds on the OAuth 2.0 Framework and optionally OpenID Connect (OIDC), to allow third-party applications to securely obtain authorized access to protected healthcare data exposed as APIs by the Platform.

Moreover, many such applications operate within the context of a specific Patient or a particular Episode. Therefore, selection of the appropriate context becomes a critical prerequisite for launching the Application.

3. Application Registration

Before an Application can integrate with a Platform, it must first be registered. This registration process establishes a trusted relationship between the Application Vendor and the Platform Vendor, and includes the configuration of necessary parameters for authentication, authorization, and launch.

The registration process includes the following steps:

  • The Application registers with the Platform by submitting metadata such as:

    • Application name, logo and identifier

    • Authorized domains and redirection URIs (redirect_uri)

    • Supported launch contexts (e.g., patient, practitioner)

    • Application type (e.g., confidential or public client)

    • Client JSON Web Keys (JWKs) or a JWK Set URL

    • Requested OAuth 2.0 scopes

  • Upon successful registration, the Platform issues credentials to the Application, such as:

    • A unique client_id (always required)

    • A client_secret (for confidential clients)

    • Optionally, a set of JSON Web Keys (JWKs) or a JWK Set URL (jwks_uri) for JWT-based client authentication

These credentials are used in subsequent OAuth 2.0 flows to authenticate the Application and enable secure, scoped access to protected resources.

The SMART App Launch Framework describes a corresponding registration flow, including support for registering public keys using jwks or jwks_uri to enable secure client authentication. The SMART on openEHR specification adopts a compatible approach, extending these mechanisms for use with openEHR-based APIs and platforms.

While this registration process could be formalized and automated using the OAuth 2.0 Dynamic Client Registration Protocol, the current recommendation is to handle registration out-of-band in a way that is practical for both the Application Vendor and the Platform Vendor. For example, the Platform may provide a dedicated registration portal where Application Vendors can submit their applications for review. This portal may support approval workflows, audit trails, and administrative oversight before issuing credentials, ensuring that only vetted applications are authorized to interact with the Platform.

4. Service Discovery

A Platform typically exposes multiple service endpoints. These include OAuth 2.0 endpoints such as Authorization and Token, standard data service endpoints (e.g., openEHR REST APIs, FHIR APIs), and possibly other standard or proprietary APIs (e.g. DICOMWeb APIs).

The SMART Service Discovery mechanism extends the FHIR .well-known/smart-configuration endpoint definition. It allows a Platform to advertise authentications endpoint, SMART capabilities, and a list of available services.

smart service discovery
Figure 1. SMART Service Discovery

The configuration endpoint should be always available relative to the Platform base URL. For example, given a base URL as https://platform.example.com, the SMART configuration endpoint must be available at https://platform.example.com/.well-known/smart-configuration. If the base URL includes a path segment as https://platform.example.com/gateway/v1, then the configuration should be accessible at https://platform.example.com/gateway/v1/.well-known/smart-configuration.

Unlike the FHIR .well-known/smart-configuration, which defines the configuration endpoint relative to the base URL of the FHIR server, this specification defines this endpoint relative to the Platform base URL (i.e. the gateway). This allows the Platform to advertise service capabilities beyond FHIR APIs, including openEHR REST APIs and other APIs that may not be part of the FHIR server itself. While this provides greater flexibility and aligns with a multi-API architecture, Platform vendors are encouraged to ensure compatibility with SMART FHIR applications by maintaining a consistent issuer and exposing the FHIR API at the same base URL when feasible.

Note

In order to maintain compatibility with SMART App Launch, it is recommended that the base URL of the Platform also acts as the base URL of the FHIR server. Such applications often assume the iss (issuer) launch parameter is both the base FHIR endpoint and the issuer value in the configuration document. Platform vendors may implement this alignment using gateways, proxies, or redirection mechanisms. However, such implementation details are outside the scope of this specification.

Responses to /.well-known/smart-configuration endpoint must be served with the application/json MIME type. A representative example is shown below:

{
  "issuer": "https://platform.example.com",
  "jwks_uri": "https://platform.example.com/.well-known/jwks.json",
  "authorization_endpoint": "https://platform.example.com/auth/authorize",
  "token_endpoint": "https://platform.example.com/auth/token",
  "services": {
    "org.openehr.rest" : {
      "baseUrl":"https://platform.example.com/openehr/rest/v1",
      "description": "The openEHR REST APIs baseUrl",
      "documentation": "https://example.com/openehr/docs",
      "openapi": "https://example.com/openehr/rest/v1/openapi.json"
    },
    "org.fhir.rest" : {
      "baseUrl":"https://platform.example.com/",
      "description": "The FHIR APIs baseUrl"
    },
    "com.amazon.aws.s3.rest": {
      "baseUrl":"https://s3.example.com/storage",
      "documentation": "https://example.com/s3/docs",
      "openapi": "https://example.com/s3/openapi.json"
    },
    "com.example.demographics": {
      "baseUrl":"https://demographics.example.com/rest"
    }
  },
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "private_key_jwt"
  ],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials"
  ],
  "registration_endpoint": "https://platform.example.com/auth/register",
  "scopes_supported": ["openid", "profile", "launch", "launch/patient", "patient/*.rs", "user/*.rs", "offline_access"],
  "response_types_supported": ["code"],
  "management_endpoint": "https://platform.example.com/user/manage",
  "introspection_endpoint": "https://platform.example.com/user/introspect",
  "revocation_endpoint": "https://platform.example.com/user/revoke",
  "code_challenge_methods_supported": ["S256"],
  "capabilities": [
    "launch-ehr",
    "permission-patient",
    "permission-v2",
    "client-public",
    "client-confidential-symmetric",
    "context-ehr-patient",
    "sso-openid-connect",
    "context-openehr-ehr",
    "openehr-permission-v1",
	"launch-base64-json"
  ]
}

The details of the /.well-known/smart-configuration are described in the sections below.

4.1. Authentication Endpoints

The following attributes in the .well-known/openid-configuration must match those defined in the OAuth 2.0 + OpenID Connect Discovery specification as well as the FHIR SMART metadata specification:

  • issuer

  • jwks_uri

  • authorization_endpoint

  • grant_types_supported

  • token_endpoint

  • token_endpoint_auth_methods_supported

  • registration_endpoint

  • scopes_supported

  • management_endpoint

  • response_types_supported

  • introspection_endpoint

  • revocation_endpoint

  • capabilities

  • code_challenge_methods_supported

4.2. Services

In addition to the FHIR-specific metadata, the response from configuration endpoint must include the services section describing the available service interfaces exposed by the Platform. This section enables Applications to dynamically discover the APIs provided by the Platform, along with their respective base URLs, descriptions, and potentially documentation links.

The services is a hash map, where each key is a reverse domain name uniquely identifying a service (e.g., org.openehr.rest), and the corresponding value contains the service-specific metadata and base URL. This structure allows for a flexible and extensible way to declare multiple APIs that may coexist within the Platform.

At a minimum, the services section must include the openEHR REST API using the key org.openehr.rest. For consistency reason, it is also recommended to include the FHIR API under the key org.fhir.rest:

  • org.openehr.rest: The base URL of the openEHR REST APIs (required)

  • org.fhir.rest: The base URL of the FHIR APIs (recommended)

Additional services, such as CDS Hooks endpoints, terminology services, or non-RESTful interfaces, may be included using appropriately namespaced keys. For example:

  • org.dicomstandard.dicomweb.rest: DICOMWeb REST API endpoint

  • com.amazon.aws.s3.rest: AWS S3-compatible REST API

  • com.example.demographics: A vendor-specific demographic service

Each service definition may contain:

  • baseUrl: Absolute URL to the root of the API (required)

  • description: Human-readable description of the service

  • version: Service API version

  • documentation: Link to service documentation

  • openapi: Link to the OpenAPI (Swagger) definition of the API

Example:

{
    "org.openehr.rest" : {
        "baseUrl": "https://platform.example.com/openehr/rest/v1",
        "description": "The openEHR REST API baseUrl",
        "documentation": "https://platform.example.com/openehr/docs",
        "openapi": "https://platform.example.com/openehr/rest/v1/openapi.json"
    }
}

4.3. Capabilities

The capabilities section advertises supported SMART features as an array value. In addition to those scopes defined in the original SMART App Launch framework, the following capabilities extend the list for openEHR platforms:

  • context-openehr-ehr: Indicates support for EHR-level launch context, requested via launch/patient scope and conveyed via the ehrId token claim.

  • context-openehr-episode: Indicates support for Episode-level context, requested via launch/episode, scope conveyed via episodeId (experimental).

  • openehr-permission-v1: Indicates support for fine-grained scopes and authorization scheme over openEHR resources.

  • launch-base64-json: Indicates support for encoding launch context as a base64-encoded JSON object in the launch parameter.

5. Application Types

The appropriate authentication flow depends on the type of the client Application, particularly its ability to securely manage credentials and the nature of its interaction with users or backend services. The SMART on openEHR specification defines two fundamental client types based on credential handling capabilities, and further distinguishes applications by their interaction model.

5.1. Classified by Credential Handling

The following client application types are defined by the considered by SMART specification based on their ability to securely manage secrets or to secure the client authentication using other means:

  • Confidential applications: These applications can securely hold credentials such as a client_secret or private keys. This category includes backend services, server-side web applications, and applications using hardware security modules or additional technology for higher security.

  • Public applications: These applications cannot securely store secrets. This includes native mobile apps and single-page web applications (SPAs) running in browsers. For these apps, authentication must rely on flows that do not require client credentials (e.g., PKCE).

The distinction between public and confidential clients is essential in determining the appropriate OAuth2 flow, and impacts which tokens can be safely issued and under what conditions.

5.2. Classified by User Interaction

Applications are also classified by the context in which they are launched and the nature of their end-users:

  • Patient-facing applications: These applications are used directly by the patient, or are launched by a practitioner in the context of a specific patient. Optionally, the launch may be tied to a particular episode of care.

  • Practitioner-facing applications: These applications are used by healthcare professionals and may operate within or outside the context of a specific patient or episode.

  • Backend services: These applications operate autonomously without direct user interaction. They are typically used for system-to-system communication or background processing, such as synchronization, analytics, or alerts.

6. Authentication

In line with the SMART framework, authentication is typically an integral part of the OAuth 2.0 authorization process. For verifying end-user identity, an external identity provider is expected, typically using OpenID Connect (OIDC). While OIDC is the recommended approach, the exact mechanisms of identity verification are considered implementation-specific and fall outside the scope of this specification.

6.1. Supported Authentication Flows

Client Applications may authenticate with the Platform using one of the following OAuth2-compatible flows. The choice of flow depends on the client application type (public vs. confidential) and the desired security posture.

Platform implementation must clearly advertise which flows are supported in its .well-known/smart-configuration metadata document. This allows clients to dynamically determine how to authenticate and obtain tokens.

6.2. Client Authentication Methods

SMART distinguishes two main authentication methods for confidential clients:

6.3. Deprecated Flows

The following OAuth 2.0 flows are discouraged and MUST NOT be used within SMART on openEHR due to security concerns:

6.4. Flow Recommendations

The following recommendations apply based on client type and use case:

These flows ensure secure and appropriate access to the Platform based on the capabilities and deployment context of the application.

The table below illustrates recommended flows for common application scenarios:

Application Example Client Type User Interaction Type Recommended Flow

Single Page Web Application for a Patient Portal

Public

Patient-facing

Authorization Code Grant with PKCE

Mobile Application for Tracking Heart Rate

Public

Patient-facing

Authorization Code Grant with PKCE

Web Application with Backend for Cardiology Management

Confidential

Practitioner-facing

Authorization Code Grant with PKCE or Authorization Code Grant with client_secret

Realtime Alert System for Hospital

Confidential

Backend service

JWT Bearer Token Grant with JWS or Client Credentials Grant

7. Authorization

Both patient-facing and practitioner-facing applications have specific authorization requirements that extend beyond the capabilities of the core OAuth 2.0 Authorization Framework. Depending on how an application is invoked, SMART Framework defines two launch contexts, enabling apps to obtain contextual access to clinical data based on the user and their session:

  1. Standalone Launch: The Application is initiated directly by the end-user, outside the context of a running session on the Platform. For example, the user may visit https://myapp.example.com and select the Platform instance they want to connect to. The Application then begins the SMART authorization sequence using the selected Platform’s base URL and .well-known/smart-configuration metadata.

  2. EHR Launch: The Application is launched from within the Platform’s user interface (typically within an iframe within a Portal). The Platform passes the iss (issuer) and launch parameters to the Application, such as in https://myapp.example.com?launch=123&iss=https://platform.example.com. The iss identifies the Platform (FHIR server), and the launch parameter conveys session-specific information used to retrieve additional context data.

Note

To avoid confusion with the openEHR Reference Model’s EHR class, the EHR Launch is in this document referred to as an Embedded iFrame Launch.

7.1. SMART Authorization Flow

The SMART framework builds on the OAuth 2.0 Authorization Code Flow and defines several SMART-specific launch enhancements on how to obtain the authorization code:

  1. The Application redirects the user to the Platform’s authorization_endpoint, including SMART-specific query parameters such as aud, launch, scope, state, redirect_uri, etc.

  2. The Authorization Server authenticates the user, validates the requested scopes, and (if allowed) issues an authorization code to the Application via the redirect_uri.

  3. The Application exchanges the authorization code for an access_token and optionally an id_token and refresh_token by POSTing to the Platform’s token_endpoint.

7.2. Context Selection

In a Standalone Launch, a client Application can request the Platform to assist with context selection, provided that the relevant capabilities are supported by the Platform. Most patient-facing and practitioner-facing applications will require the Platform to supply additional context during the authorization process. This contextual data may include identifiers such as the openEHR EHR ID, FHIR Patient ID, Episode ID, etc. The context is typically valid for the duration of the user session.

smart standalone launch
Figure 2. Standalone Launch

The purpose of this context data is to pre-load or configure the Application to operate within a relevant clinical scope. The Platform may determine this context automatically based on the authenticated user, or may prompt the user (e.g., via a selection screen) after the consent page if multiple valid contexts are possible.

To explicitly request openEHR-related launch context, the Application must include the following SMART-defined scopes in the authorization request:

Scope Meaning

launch/patient

Indicates that the Application requires patient context at launch (both FHIR Patient resource and corresponding openEHR EHR instance). For Standalone Launch, the user should be prompted to select the openEHR EHR.

launch/episode

Indicates that the Application requires episode context at launch. (Experimental)

The Platform returns the resolved context information in the token response, alongside the access_token and optionally an id_token. In addition to the standard SMART App Launch context attributes, the following openEHR-specific parameters may be included in the token response:

Parameter Meaning

ehrId

The unique identifier of the openEHR EHR instance associated with the selected FHIR Patient resource.

episodeId

The identifier of the selected clinical episode (if applicable). (experimental)

The Application may use these parameters to tailor the user interface and functionality to the selected clinical context.

Note

While this specification defines openEHR-specific launch parameters, standard SMART launch scopes and context attributes remain compatible and may be used in parallel for interoperability purposes. These are referenced from the SMART App Launch Framework, but their use is not normative in this specification.

7.3. Embedded iFrame Launch

Many practitioner-facing applications and, in some cases, patient-facing applications are integrated directly within a web-based front-end (e.g., a clinical portal or patient portal) using a dedicated component.

In an Embedded iFrame Launch, the Platform initiates the application by embedding it in an iFrame and passing key parameters directly in the URL:

  • launch: An opaque identifier or token that encodes relevant launch context (e.g., patient, EHR ID, episode).

  • iss: The issuer URL representing the Platform’s base endpoint (which, for compatibility with SMART on FHIR, should also serve as the FHIR base URL).

For example, an application might be launched by: https://myapp.example.com?launch=123&iss=https://platform.example.com.

smart embedded iframe launch
Figure 3. Embedded iFrame Launch

Once launched, the Application uses the iss value to retrieve the SMART configuration document from {iss}/.well-known/smart-configuration.

This configuration document provides important endpoints including the authorization_endpoint. The Application uses this information to initiate the OAuth 2.0 Authorization Code Flow, including the launch parameter in the authorization request.

To support this interaction model, the following SMART-defined scope must be also included in the authorization request:

Scope Meaning

launch

Permission to obtain launch context when Application is launched from an EHR (i.e., Embedded iFrame Launch). Must be accompanied by the launch parameter in the authorization request.

8. Scopes

Authorization is governed by scopes, which define the type and extent of access that a client Application is requesting from the Platform.

As specified in OAuth 2.0 Section 3.3, scopes are passed during the authorization request and are evaluated by the Platform when issuing access tokens. The Platform must validate requested scopes against the Application registration metadata, applicable access control policies, the authenticated user’s permissions.

SMART on openEHR aligns with FHIR’s SMART App Launch Framework, where scopes serve three main purposes:

  • Resource Access: Grant access to specific resource types (e.g., patient/composition-\*.rs).

  • Context Declaration: Request specific launch contexts (e.g., launch/patient).

  • Identity Claims: Enable OpenID Connect scopes (e.g., openid) to identify the user.

8.1. Resource Scopes

The Application can request access to the Platform resources using the scope syntax <compartment>/<resource>.<permission> where:

  • <compartment> indicates the scope of access delegation:

    • patient: Access is limited to the current EHR and Patient is present in the context.

    • user: Access is granted based on the authenticated user’s permissions.

    • system: Access is granted to backend applications acting without a user context.

  • <resource> identifies the openEHR or derived asset being accessed.

  • <permissions> specifies the allowed operations.

The following <compartment> are supported:

  • patient: For applications acting in the context of a specific patient/EHR. Access is restricted to data within that patient’s EHR.

  • user: For applications acting on behalf of a logged-in user (e.g., a practitioner). Access is subject to the user’s security profile, not limited to the Patient in context (if any is present).

  • system: For server-to-server integrations or backend services, typically using client credentials, based on pre-configured client-specific policy. Grants access across all data.

The following openEHR REST APIs <resource> types are supported for use in scopes:

  • template-<templateId> - Access to operational templates matching <templateId> expression.

  • composition-<templateId> - Access to compositions of a given template matching <templateId> expression.

  • aql-<queryName> - Access to pre-defined (matching <queryName> expression) or ad-hoc (using wildcard *) AQL queries.

The <templateId> and <queryName> support wildcard and pattern-based matching using * and **, as follows:

Pattern Matches

MyHospital::Template.v0

Template exact match only

org.openehr::bloodpressure.v1

Query exact match only

*::Template.v0

Template.v0 from any namespace

MyHospital::*

Any template within MyHospital namespace

*

All available templates or queries

The following permission expressions are supported:

  • c - Create

  • r - Read

  • u - Update

  • d - Delete

  • s - Search or execute (e.g., for AQL queries)

Note

Wildcard-based scopes (e.g., * or **) should be used cautiously and only when absolutely necessary, as they imply broad access. For example, system/aql-*.rs would grant access to all registered and ad-hoc AQL queries system-wide.

The following table is a maximal representation of the scopes made possible in different compartment, resource and permission combinations:

Scope Description

patient/composition-<templateId>.crud

Full CRUD access to compositions matching <templateId> in the current patient’s EHR.

user/composition-<templateId>.crud

Full CRUD access to compositions accessible by the user.

system/composition-<templateId>.crud

Unrestricted CRUD access to compositions across the entire system.

user/template-<templateId>.crud

Create and manage templates accessible to the user.

system/template-<templateId>.crud

Full system-wide template management.

patient/aql-<queryName>.rs

Execute and read AQL queries on the patient’s EHR data.

user/aql-<queryName>.cruds

Full access to user-permitted AQL definitions or ad-hoc queries.

system/aql-<queryName>.cruds

System-wide access to AQL queries and endpoints.

9. Experimental features

The following concepts and aspects are considered experimental.

Note

Implementers should treat its use as provisional and subject to change in future versions of this specification.

9.1. Launch Parameter as a Token

To support efficient and context-rich embedded launches, it is recommended that the launch parameter be a base64-encoded JSON object containing launch context attributes such as:

  • ehrId - The openEHR EHR identifier

  • patient - FHIR Patient ID (if available)

  • episodeId - Clinical episode ID (optional)

This allows the Application to initialize its interface with full context and potentially bypass a full authorization cycle if it is already authenticated. This significantly improves the user experience, for instance, when switching patients within the same embedded session.

Platforms that support this optimization should advertise the following capabilities in their /.well-known/smart-configuration response:

  • launch-base64-json: May be used to deliver context (including episodeId) in a base64-encoded JSON format for embedded iFrame launches.

9.2. Experimental: Episode Context

The Episode concept represents a bounded period of care or clinical workflow, such as a hospital admission, treatment course, or referral. It serves as a logical container for grouping related clinical activities, encounters, and observations. This concept is particularly relevant for workflows where context must be maintained across multiple interactions or systems.

In the context of SMART on openEHR, Episode selection and usage is considered experimental. While the openEHR specification outlines the concept of an Episode, formal resource definitions and operational semantics are still evolving. As the openEHR specification evolves to formalize Episode as a first-class resource, the following enhancements may be introduced:

  • Standardized resource representation of an Episode type or new archetype.

  • Extended query support for filtering by Episode.

  • Improved UI/UX support in authorization servers for Episode selection.

  • FHIR mapping for Episode-related concepts.

This section outlines the current capabilities and usage patterns under evaluation for Episode support.

9.2.1. Scopes and Capabilities

To request Episode context during an authorization flow, the following scope may be included in the authorization request:

Scope Description

launch/episode

Requests Episode context at launch time. If launching outside an EHR, prompts the Platform to determine or allow selection of the Episode relevant to the session.

Platforms that support Episode context should advertise the following capabilities in their /.well-known/smart-configuration response:

  • context-openehr-episode: Indicates that the Platform supports Episode context selection during launch, requested via launch/episode scope.

9.2.2. Token Response Parameters

When an authorization request includes launch/episode scope and the Platform is capable of resolving the Episode, the following parameter will be included in the token response:

Parameter Description

episodeId

Identifier of the selected or inferred Episode for the session. This may map to an openEHR EHR_STATUS.episode or a platform-specific abstraction. Its semantics are currently implementation-defined.

This value is intended to be used by the client Application to filter or group clinical data relevant to the specific Episode of care.

9.2.3. Launch Scenarios

Standalone Launch: When the launch/episode scope is included, the Platform may prompt the user to select an Episode or infer it automatically based on session context (e.g., currently admitted case, recent discharge summary, etc.).

Embedded iFrame Launch: Episode context may be embedded in a base64-encoded launch parameter provided at runtime. This can improve usability by avoiding a separate Episode selection prompt during intra-portal navigation.

References