International Patient Access
0.1.0 - draft

International Patient Access, published by HL7. This is not an authorized publication; it is the continuous build for version 0.1.0). This version is based on the current content of and changes regularly. See the Directory of published versions

Gaining Access to a patient record

An application gets access to a patient record using the Smart App Launch Protocol, using the stand alone launch sequence.

Client Process

A client application gets access a patient record by following this general sequence of steps:

  • Identifying the appropriate end point [URL] at which the International Patient Access API is found.
    • Note that this specification does not specify how the end-point might be found; different countries will have different arrangements around this
  • Fetch the system capability statement from [url]/metadata and check that it implements the IPA API:

    "imports" : [""]

  • Fetch the end-point configuration from [url]/.well-known/smart-configuration.json

  • Registering itself as a client application with the end-point.
    • This may require a manual step on the part of the user or the developer, or the end-point may support automatic registration (see OAuth 2.0 Dynamic Client Registration Protocol).
    • if the application supports automatic registration, the end-point will be specified in the [url]/.well-known/smart-configuration.json
    • note that most healthcare systems exercise control over which clients can access healthcare records, and automatic registration is not supported
  • Follow the Smart App Launch Protocol using the authorization endpoint from the smart-configuration.json file

  • At the end of the Smart App Launch Protocol, the application will have a token that provides access to a single patient record. Now, use that to retrieve patient infomration


Scopes work as described in the Smart on FHIR specification, but note that many servers limit a server to the scopes approved on it’s registration, and/or ignore the requested scopes at the initiation of the stand-alone launch.

Server Obligations

Servers that are conformant to the International Patient Access API conform to the following rules:

  • The server hosts a capability statement at [url]/metadata that is available to both authenticated and unauthenticated clients, and that declares that IPA is supported using CapabilityStatement.imports, as shown in the following fragment:

    "imports" : [""]

  • The server hosts a smart-configuration file at [url]/.well-known/smart-configuration.json that is available to both authenticated and unauthenticated clients
  • The server conforms to the Smart App Launch specification, and checks that the authenticated user of the application has access
  • If the client requests access to a patient record, checks that the authenticated user of the application has access to the specified record
  • If the client does not nominate a particular patient record, requires that the user must choose a single patient record to which the application has access
  • enforces patient privacy and consent

Note that both the CapabilityStatement and the smart configuration file may be different for authenticated and unauthenticated clients.