EU Health Data API
0.1.0 - ci-build
150
EU Health Data API, published by HL7 Europe. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/euridice-org/eu-health-data-api/ and changes regularly. See the Directory of published versions
Authorization is required for all API transactions. This IG inherits SMART Backend Services from FHIR SMART App Launch for system-to-system authorization, grouped with IHE IUA actors.
We adopt SMART Backend Services as specified—including grant types, client authentication (private_key_jwt), and related JWT requirements—to align with globally recognized specifications and reduce implementation burden. As a profile on SMART, all underlying SMART requirements still apply; omitting a detail from this IG does not exempt implementations from SMART requirements.
Note: This IG uses IHE IUA actor definitions grouped with SMART Backend Services normative requirements. Where requirements differ, SMART Backend Services is authoritative.
This specification defines system-to-system authorization only:
User-level authorization requirements are not in initial scope for this Implementation Guide.
IHE IUA defines three key actors for authorization:
The Authorization Server may be internal (bundled with the Access Provider), or external (external to the Access Provider, for example a hospital, regional, or national authorization server). When external, the Access Provider system implements only Resource Server behaviors—this IG does not impose requirements on external authorization infrastructure.
sequenceDiagram
participant Client as Document Consumer<br/>(IUA Authorization Client)
participant AP as Document Access Provider<br/>(IUA Authorization Server / IUA Resource Server)
Note over Client,AP: Prerequisite: Client Registration (out of band)
Client-->>AP: Register public key, client identifier
Note over Client,AP: 1. Discovery
Client->>AP: GET /.well-known/smart-configuration
AP-->>Client: {"token_endpoint": "...", ...}
Note over Client,AP: 2. Get Access Token (ITI-71)
Client->>AP: POST [token_endpoint] (client_credentials, signed JWT)
AP-->>Client: Access Token
Note over Client,AP: 3. Incorporate Access Token (ITI-72)
Client->>AP: GET [base]/Patient?identifier=... (Bearer token)
AP-->>Client: Bundle (search results)
This diagram shows the internal Authorization Server deployment. See External Authorization Server for the external variant.
Out of band, the Consumer registers identity credentials (public key, client identifier) with the Authorization Server (which may be hosted by the Access Provider). See SMART App Launch: Registering a Client for guidance on client registration and public key communication.
Resource Servers SHALL advertise their authorization configuration at [base]/.well-known/smart-configuration, per SMART App Launch conformance.
For backend services, clients use:
token_endpointgrant_types_supported (include client_credentials)jwks_uri (when the Authorization Server publishes keys via JWKS)capabilities (include client-confidential-asymmetric when private_key_jwt is supported)Resource Servers SHOULD advertise:
scopes_supportedIf the server supports private_key_jwt client authentication, it SHOULD advertise:
token_endpoint_auth_methods_supported including private_key_jwttoken_endpoint_auth_signing_alg_values_supported including at least one of RS384 or ES384 (per SMART client-confidential-asymmetric)See SMART Backend Services Discovery for the full specification.
Clients obtain tokens by POSTing to the token endpoint discovered via .well-known/smart-configuration.
Token Request:
client_credentialsToken Issuance:
The Authorization Server issues access tokens to registered clients using the client_credentials grant.
Authorization Servers SHALL validate private_key_jwt client authentication (including client assertion signature verification and required claims) per SMART client-confidential-asymmetric, and issue tokens with scopes based on client authorization.
Clients SHALL present the access token using the Authorization header:
Authorization: Bearer <access_token>
The access token SHALL be presented on all API requests to protected resources.
Resource Servers SHALL validate the access token, ensure that it has not expired, and that its scope covers the requested resource, per SMART Backend Services. The method used to validate the access token is beyond the scope of SMART Backend Services and generally involves coordination between the Resource Server and Authorization Server.
In deployments using an external Authorization Server, token validation commonly involves coordination with that Authorization Server; where supported and required by policy, Resource Servers MAY use token introspection via IHE IUA ITI-102.
Scopes follow SMART v2 conventions and align with required MHD and IPA transactions:
system/DocumentReference.create - Create DocumentReferencesystem/Patient.read - Read Patient (for patient context)system/Patient.search - Search Patient (for patient matching)system/Patient.read - Read Patientsystem/Patient.search - Search Patientsystem/DocumentReference.read - Read DocumentReferencesystem/DocumentReference.search - Search DocumentReferencesystem/Binary.read - Read Binarysystem/Bundle.read - Read Bundle (for FHIR Documents)system/Patient.read - Read Patientsystem/Patient.search - Search Patientsystem/Observation.read, system/Observation.search, system/Condition.read, system/Condition.search, system/DiagnosticReport.read, system/DiagnosticReport.search, etc..read = read a single resource by ID.search = search for resources by criteria.create = create a new resourceWhen the Authorization Server is external (hospital, regional, or national infrastructure):
sequenceDiagram
participant Client as Document Consumer<br/>(IUA Authorization Client)
participant AP as Document Access Provider<br/>(IUA Resource Server)
participant AS as (External Authorization Server)
Note over Client,AS: Prerequisite: Client Registration (out of band)
Client-->>AS: Register public key, client identifier
Note over Client,AP: 1. Discovery
Client->>AP: GET /.well-known/smart-configuration
AP-->>Client: {"token_endpoint": "https://as.example/token", ...}
Note over Client,AS: 2. Get Access Token (ITI-71)
Client->>AS: POST [token_endpoint] (client_credentials, signed JWT)
AS-->>Client: Access Token
Note over Client,AP: 3. Incorporate Access Token (ITI-72)
Client->>AP: GET [base]/DocumentReference?patient=123 (Bearer token)
opt Token Introspection (ITI-102)
AP->>AS: POST [introspection_endpoint]
AS-->>AP: Token claims
end
AP-->>Client: Bundle (search results)
All API communications SHALL use secure transport as defined by IHE ATNA Secure Node with the TLS 1.2 Floor Option.
This IG uses IHE IUA for actor definitions and groups those actors with SMART Backend Services behavior. IUA itself notes its relationship to SMART-on-FHIR: "IUA is not based on SMART-on-FHIR, but does strive to not conflict with that standard."
Where IUA and SMART Backend Services requirements differ, this IG follows SMART.
For example: this IG requires private_key_jwt client authentication (per SMART Backend Services). While client_secret with HTTP Basic Auth is IUA-compliant, it is NOT compliant with this IG.
User-level authorization (including patient-mediated access) is out of scope for this version of the implementation Guide. For patient-mediated access patterns, readers are encouraged to consider SMART on FHIR App Launch and International Patient Access. Implementors might consider UDAP for dynamic client registration (see FHIR UDAP Security IG).
Integration with the EU Digital Identity Wallet and eIDAS framework may be addressed in future editions.
Member States MAY layer user-level authorization on top of system-to-system authorization as appropriate for their national infrastructure.