SMART Health Cards and Links FHIR IG, published by HL7 International / FHIR Infrastructure. This guide is not an authorized publication; it is the continuous build for version 1.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/smart-health-cards-and-links/ and changes regularly. See the Directory of published versions

Health Links Specification

Use Cases

• Share a link to any collection of FHIR data, including signed data
• Share link to a static SMART Health Card that’s too big to fit in a QR
• Share link to a “dynamic” SMART Health Card – i.e., a file that can evolve over time (e.g., “my most recent COVID-19 lab results”)
• Share a link to Bundles of patient-supplied data (e.g., “my advance directive” to share with EMS, or “my at-home weight measurements” to share with a weight loss program, or “my active prescriptions” to share with a service that helps you find better drug prices)
  • Note that for specific use cases, these data don’t need to be tamper-proof, and could be aggressively stripped down (e.g., for a drug pricing service, just the drug codes and dosage would go a long way)
• Provision access to a patient’s SMART on FHIR API endpoint (e.g., “I’m going to see a specialist and by presenting a single QR, I can give them access to the FHIR API from my primary care provider’s portal”)

Design Goals

• Allow sharing of tamper-proof data
• Allow sharing of non-tamper-proof data
• Allow long-term sharing of data
• Allow sharing data that can evolve over time
• Mitigate the damage of QRs being leaked or scanned by the wrong party
  • Allow generate of “one-time use” QR (or a limited-time use QR), so at the time of creation there’s a limited number of “claims” or a limited time period attached to it
  • Allow protecting the QR with a PIN, which the Sharer can communicate the PIN to the Recipient out-of-band
• Give Data Sharers the option to host files using encrypted cloud storage, so the hosting provider can’t see file contents. (This is mainly important in cases where the data originates from a clinical data system but passes through the consumer’s hands and then is hosted online in a cloud service of the consumer’s choice. For example, a consumer health app might periodically upload a “most recent labs” file compiled from various sources, and the consumer shouldn’t need to trust the file hosting service to actually see plaintext lab results.)
• Offer a simple UX where Data Recipients can scans a QR and immediately retrieve the data
• Offer a glide path for upgraded assurance, e.g. allowing Data Sharers to define a PIN or even (someday) require the Data Recipient party to authenticate or id-proof before accessing shared data

Actors

• Software Applications
  • SMART Health Links Sharing Application. Software that is used to create, manage, and share SMART Health Links. Also referred to below as “server”. This application can include local software as well as server-side components.
  • SMART Health Links Receiving Application. Software that enables users to receive and access health information shared through SMART Health Links. Also referred to below as a “client”, this application can take many forms, including a lightweight web page with Javascript, a full-fledged module in a native EHR system, or a standalone mobile app.
• Users
  • Sharing User. An individual working with a SMART Health Links Sharing Application to create/manage/share information
  • Receiving User. An individual working with a SMART Health Links Receiving Application to retrieve/display/use information. In autonomous use cases there may be no Receiving User.

Pre-protocol step: Sharing User configures a new SMART Health Link

Working with a SMART Health Links Sharing Application, the Sharing User makes a few decisions up front:

• What to share. Depending on the SMART Health Links Sharing Application, the Sharing User might explicitly choose a set of files or define a “sharing policy” that matches different data over time.
• Whether the SMART Health Links will require a Passcode to access. Depending on the SMART Health Links Sharing Application, a Passcode may be mandatory.
• Whether the SMART Health Links will expire at some pre-specified time. Depending on the SMART Health Links Sharing Application, an expiration time may be mandatory.

Regarding “what to share”: a single SMART Health Link at a specific point in time will resolve to a manifest of files of the following types:

• application/smart-health-card: a JSON file with a .verifiableCredential array containing SMART Health Card JWS strings, as specified in the via File Download section of the SMART Health Cards specification.
• application/fhir+json: a JSON file containing any FHIR resource (e.g., an individual resource or a Bundle of resources). Note that this format is not inherently tamper-proof, but the content may be include digital signatures or have other verification processes associated with it, which are not defined here.
• application/smart-api-access: a JSON file with a SMART Access Token Response (see SMART App Launch). Two additional properties are defined:
  • aud Required string indicating the FHIR Server Base URL where this token can be used (e.g., "https://server.example.org/fhir")
  • query: Optional array of strings acting as hints to the client, indicating queries it might want to make (e.g., ["Coverage?patient=123&_tag=family-insurance"])

At configuration time, the SMART Health Links Sharing Application SHALL generate a random key used for encrypting/decrypting the files in the manifest (see “Decryption”).

SMART Health Links Sharing Application Generates a SMART Health Link URI

Establish a SMART Health Link Manifest URL

Based the configuration from (1), the SMART Health Links Sharing Application generates a “manifest URL” for the new SMART Health Links. The manifest URL:

• SHALL include at least 256 bits of entropy
  • A suggested approach is to generate a cryptographically strong 32-byte random sequence and then base64url-encode this sequence to obtain a 43-character string that is used as a path segment. For example: https://shl.example.org/manifests/I91rhba3VsuGXGchcnr6VHlQFKxfE28kuZ0ssbEuxno/manifest.json
• SHALL NOT exceed 128 characters in length (note, this maximum applies to the url field of the SMART Health Link Payload, not to the entire SMART Health Link URI).

The SMART Health Links Sharing Application incorporates the manifest URL into a SMART Health Link as described below.

Construct a SMART Health Link Payload

The SMART Health Link Payload is a JSON object including the following properties:

• url: Manifest URL for this SMART Health Links
• key: Decryption key for processing files returned in the manifest. 43 characters, consisting of 32 random bytes base64urlencoded.
• exp: Optional. Number representing expiration time in Epoch seconds, as a hint to help the SMART Health Links Receiving Application determine if this QR is stale. (Note: epoch times should be parsed into 64-bit numeric types.)
• flag: Optional. String created by concatenating single-character flags in alphabetical order
  • L Indicates the SMART Health Link is intended for long-term use and manifest content can evolve over time
  • P Indicates the SMART Health Link requires a Passcode to resolve
  • U Indicates the SMART Health Links’s url resolves to a single encrypted file accessible via GET, bypassing the manifest. SHALL NOT be used in combination with P.
• label: Optional. String no longer than 80 characters that provides a short description of the data behind the SMART Health Links.
• v: Optional. Integer representing the SMART Health Links protocol version this SMART Health Link conforms to. MAY be omitted when the default value (1) applies.

The JSON Payload is then:

• Minified
• Base64urlencoded
• Prefixed with shlink:/
• Optionally prefixed with a viewer URL that ends with #

The following optional step may occur sometime after a SMART Health Link is generated:

• Optional: Update Shared Files. For some sharing scenarios, Sharing User MAY update the shared files from time to time (e.g., when new lab results arrive or new immunizations are performed). Updated versions SHALL be encrypted using the same key as the initial version.

Example SMART Health Link Generation

import { encode as b64urlencode } from 'https://deno.land/std@0.82.0/encoding/base64url.ts';

const shlinkJsonPayload = {
  "url": "https://ehr.example.org/qr/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM/m",
  "flag": "LP",
  "key": "rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q",
  "label": "Back-to-school immunizations for Oliver Brown"
}

const encodedPayload = b64urlencode(JSON.stringify(shlinkJsonPayload))
// "eyJ1cmwiOiJodHRwczovL2Voci5leGFtcGxlLm9yZy9xci9ZOXh3a1VkdG1OOXd3b0pvTjNmZkpJaFgyVUd2Q0wxSm5sUFZOTDNrRFdNL20iLCJmbGFnIjoiTFAiLCJrZXkiOiJyeFRnWWxPYUtKUEZ0Y0VkMHFjY2VOOHdFVTRwOTRTcUF3SVdRZTZ1WDdRIiwibGFiZWwiOiJCYWNrLXRvLXNjaG9vbCBpbW11bml6YXRpb25zIGZvciBPbGl2ZXIgQnJvd24ifQ"

const shlinkBare = `shlink:/` + encodedPayload;
// "shlink:/eyJ1cmwiOiJodHRwczovL2Voci5leGFtcGxlLm9yZy9xci9ZOXh3a1VkdG1OOXd3b0pvTjNmZkpJaFgyVUd2Q0wxSm5sUFZOTDNrRFdNL20iLCJmbGFnIjoiTFAiLCJrZXkiOiJyeFRnWWxPYUtKUEZ0Y0VkMHFjY2VOOHdFVTRwOTRTcUF3SVdRZTZ1WDdRIiwibGFiZWwiOiJCYWNrLXRvLXNjaG9vbCBpbW11bml6YXRpb25zIGZvciBPbGl2ZXIgQnJvd24ifQ"

const shlink = `https://viewer.example.org#` + shlinkBare
// "https://viewer.example.org#shlink:/eyJ1cmwiOiJodHRwczovL2Voci5leGFtcGxlLm9yZy9xci9ZOXh3a1VkdG1OOXd3b0pvTjNmZkpJaFgyVUd2Q0wxSm5sUFZOTDNrRFdNL20iLCJmbGFnIjoiTFAiLCJrZXkiOiJyeFRnWWxPYUtKUEZ0Y0VkMHFjY2VOOHdFVTRwOTRTcUF3SVdRZTZ1WDdRIiwibGFiZWwiOiJCYWNrLXRvLXNjaG9vbCBpbW11bml6YXRpb25zIGZvciBPbGl2ZXIgQnJvd24ifQ"

Sharing User transmits a SMART Health Link

The Sharing User can convey a SMART Health Link by any common means including e-mail, secure messaging, or other text-based communication channels. When presenting a SMART Health Link in person, the Sharing User can also display the link as a QR code using any standard library to create a QR image from the SMART Health Link URI.

When sharing a SMART Health Link via QR code, the following recommendations apply:

• Create the QR with Error Correction Level M
• Include the SMART Logo on a white background over the center of the QR, scaled to occupy 5-6% of the image area (inclusive of the “quiet zone” QR border).

SMART Health Links Receiving Application processes a SMART Health Link

The SMART Health Links Receiving Application can process a SMART Health Link using the following steps.

• Decode the SMART Health Link JSON payload
• Issue a SMART Health Link Manifest Request to payload’s url
• Decrypt and process files from the manifest
• Optional: When the original QR includes the L flag for long-term use, the SMART Health Links Receiving Application can re-fetch the manifest periodically, following polling guidance to avoid issing too many requests

SMART Health Link Manifest Request

When no U flag is present, the SMART Health Links Receiving Application SHALL retrieve a SMART Health Links’s manifest by issuing a request to the url with:

• Method: POST
• Headers:
  • content-type: application/json
• Body: JSON object including
  • recipient: Required. A string describing the recipient (e.g.,the name of an organization or person) suitable for display to the Receiving User
  • passcode: Conditional. SHALL be populated with a user-supplied Passcode if the P flag was present in the SMART Health Link payload
  • embeddedLengthMax: Optional. Integer upper bound on the length of embedded payloads (see .files.embedded)

If the SMART Health Link is no longer active, the Resource Server SHALL respond with a 404.

If an invalid Passcode is supplied, the Resource Server SHALL reject the request and SHALL enforce a total lifetime count of incorrect Passcodes for a given SMART Health Links, to prevent attackers from performing an exhaustive Passcode search. The error response for an invalid Passcode SHALL use the 401 HTTP status code and the response body SHALL be a JSON payload with

• remainingAttempts: number of attempts remaining before the SMART Health Links is disabled

If the SMART Health Link request is valid, the Resource Server SHALL return a SMART Health Link Manifest with content-type: application/json. The SMART Health Link Manifest is a JSON object with a files array where each entry includes:

• contentType: One of the following values:
  • "application/smart-health-card" or
  • "application/smart-api-access" or
  • "application/fhir+json"
• location (SHALL be present if no embedded content is included): URL to the file. This URL SHALL be short-lived and intended for single use. For example, it could be a short-lifetime signed URL to a file hosted in a cloud storage service (see signed URL docs for S3, Azure, and GCP).
• embedded (SHALL be present if no location is included): JSON string directly embedding the encrypted contents of the file as a compact JSON Web Encryption string (see “Encrypting”).

Polling manifest for changes

When the original QR includes the L flag for long-term use, the client MAY periodically poll for changes in the manifest. The server MAY provide a Retry-After header on successful manifest responses, indicating the minimum time that the client SHOULD wait before its next polling request. If manifest requests are issued too frequently, the server MAY respond with HTTP status 429 Too Many Requests and a Retry-After header indicating the minimum time that a client SHALL wait before re-issuing a manifest request.

.files.location links

The SMART Health Links Sharing Application SHALL ensure that .files.location links can be dereferenced without additional authentication, and that they are short-lived. The lifetime of .files.location links SHALL NOT exceed one hour. The SMART Health Links Sharing Application MAY create one-time-use .files.location links that are consumed as soon as they are dereferenced.

Because the manifest and associated files are a single package that may change over time, the SMART Health Links Receiving Application SHALL treat any manifest file locations as short-lived and potentially limited to one-time use. The SMART Health Links Receiving Application SHALL NOT attempt to dereference a manifest’s .files.location link more than one hour after requesting the manifest, and SHALL be capable of re-fetching the manifest to obtain fresh location links in the event that they have expired or been consumed.

The SMART Health Links Sharing Application SHALL respond to the GET requests for .files.location URLs with:

• Headers:
  • content-type: application/jose
• Body: JSON Web Encryption as described in Encrypting and Decrypting Files.

.files.embedded content

If the client has specified embeddedLengthMax in the manifest request, the sever SHALL NOT embedded payload longer than the client-designated maximum.

If present, the embedded value SHALL be up-to-date as of the time the manifest is requested. If the client has specified embeddedLengthMax in the manifest request, the sever SHALL NOT embedded payload longer than the client-designated maximum.

The embedded content is a JSON Web Encryption as described in Encrypting and Decrypting Files.

Example SMART Health Link Manifest

{
  "files": [{
    "contentType": "application/smart-health-card",
    "location": "https://bucket.cloud.example.org/file1?sas=MFXK6jL3oL3SI_lRfi_-cEfzIs5oHs6rRWmrsCAFzvk"
  }, 
  {
    "contentType": "application/smart-health-card",
    "embedded": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..8zH0NmUXGwMOqEya.xdGRpgyvE9vNoKzHlr4itKKW2vo<snipped>"
  },
  {
    "contentType": "application/fhir+json",
    "location": "https://bucket.cloud.example.org/file2?sas=T34xzj1XtqTYb2lzcgj59XCY4I6vLN3AwrTUIT9GuSc"
  }]
}

SMART Health Link Direct File Request (with U Flag)

When the U flag is present, the SMART Health Links Receiving Application SHALL NOT make a request for the manifest. Instead, the application SHALL retrieve a SMART Health Links’s sole encrypted file by issuing a request to the url with:

• Method: GET
  • Query parameters
    • recipient: Required. A string describing the recipient (e.g.,the name of an organization or person) suitable for display to the Data Sharer

Encrypting and Decrypting Files

SMART Health Link files are always symmetrically encrypted with a SMART Health Links-specific key. Encryption is performed using JSON Web Encryption (JOSE JWE) compact serialization with "alg": "dir", "enc": "A256GCM", and a cty header indicating the content type of the payload (e.g., application/smart-health-card, application/fhir+json, etc). The JWE MAY include a zip header with the value DEF to indicate that the plaintext of the JWE is compressed using the DEFLATE algorithm as specified in RFC 1951, before being encrypted. (Note, this indicates “raw” DEFLATE compression, omitting any zlib headers.)

Example Encryption

import * as jose from 'https://deno.land/x/jose@v4.7.0/index.ts'
import * as pako from 'https://deno.land/x/pako@v2.0.3/pako.js'

const exampleShcFromWeb = await fetch("https://spec.smarthealth.cards/examples/example-00-e-file.smart-health-card");
const exampleShcBody = new Uint8Array(await exampleShcFromWeb.arrayBuffer());
const exampleContentType = 'application/smart-health-card'

const shlinkPayload =  {
  "key": "rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q",
  // other properties omitted; not relevant for this example
};

const encrypted = await new jose
  .CompactEncrypt(new Uint8Array(exampleShcBody))
  .setProtectedHeader({
    alg: 'dir',
    enc: 'A256GCM',
    cty: exampleContentType,
  })
  .encrypt(jose.base64url.decode(shlinkPayload.key));

console.log(encrypted)
//eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiY3R5IjoiYXBwbGljYXRpb24vc21hcnQtaGVhbHRoLWNhcmQifQ..B9Bd5AW751az-gEx.iah6mxLb5TQe2ZfCwEUs4R1t8WoP0mnFc-TUzN1NIyzUeDwJNOcxv4CY8wV6ys4Dicnr3IhqTvVU1RbR-4eq1GCd4g96faV8_0MbHwXzP246Tz9BDLhQ2zlAjYqvvCi_JuWdyWqGhKeWGX1XibNHFzzVT0FmYensfKF4o0uSeZWQDKVEEhzMSKuALMpUkfwHcmCRfLT-ctANSxq-Zj0IIeT66XbztOomStjlfi-F-FaqBGZfHOARCVvT143CTYELLJCUdD4qUVkrNuLmRZrNuqVpY0g5BjABswkIoDmyoRJAEohuZCamZNA--p-uRqJjRefED1eMrKSppabV2ugaqoFlieujTOE-a3VKib9aC-lFsmLalkwh9ctr_FZqS9H46rqGjGcOxtAXalo1jkMPGupVsE1W-xIH14wbPCYcgfldH9SH7X60462kxD8OFdHpvnnfAvjQnaE4QDqasT5ySpBRtck4GVxs2IRBt62-kOlzoI8lHapLdwIms-Gdt7z38E47ZE3afE4IIbobPGz7wGvjbi3z234ARvGQ4jREgPQb1NRYAEtZlrZNzR6N7ofXD8jF502tw-QWI_Ox0jFP5tynIiMp-hG25ecQ0s4MzPHFC0ZABPamgg3MS-UILl76gMDCHS5Te_JAXZoC1HnkETw5M217SaG5ISAU0F5qETMREfTjZR9E45MDhnw7uY1vo2lffRB3ei1QqGuLh0gUnVU7TUfFYwcOqV15sb0t1lMj0mmyG5v-_dE9H6dYtRKJARltmdfSmc1HisBewx75Xh5ChJQ1hiCEDaZ1wqFjsFJ6SrKgJ7C1N7vx6QKx8YXwFH7ePG2qG39leT5JKZnqAvi9fqc6x-YwfhSjbRKGZoj2o55Fd2fbwtK6CXpiW6AekT7PUcl_7ynTq-DaQ_Yc29WwtmgapcCRNpfcMsoqCD4giu1V3Sj5DQLglwuk1gAMcuV5fo8JpABu2_is83WZ_GJ1WWMUxyZGq6u-EGuZrP96Yewb7-zfnt2lao_LJg1ef5cqDTW7-0MS27wkmLiIi0e-PYvS-UfWVHg1oNbR-MHXMVEQ6gqNg08IgEyPDSFCUbf75HuMILN80bQNtSlFj6FR7uNKHr8sigvKI80k.5flOKKmeqYm0TamwROr8Nw

Example Decryption

import * as jose from 'https://deno.land/x/jose@v4.7.0/index.ts'
import * as pako from 'https://deno.land/x/pako@v2.0.3/pako.js'

const shlinkPayload =  {
  "key": "rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q",
  // other properties omitted; not relevant for this example
};

// Output from "encrypt" example above
const fileEncrypted = "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiY3R5IjoiYXBwbGljYXRpb24vc21hcnQtaGVhbHRoLWNhcmQifQ..B9Bd5AW751az-gEx.iah6mxLb5TQe2ZfCwEUs4R1t8WoP0mnFc-TUzN1NIyzUeDwJNOcxv4CY8wV6ys4Dicnr3IhqTvVU1RbR-4eq1GCd4g96faV8_0MbHwXzP246Tz9BDLhQ2zlAjYqvvCi_JuWdyWqGhKeWGX1XibNHFzzVT0FmYensfKF4o0uSeZWQDKVEEhzMSKuALMpUkfwHcmCRfLT-ctANSxq-Zj0IIeT66XbztOomStjlfi-F-FaqBGZfHOARCVvT143CTYELLJCUdD4qUVkrNuLmRZrNuqVpY0g5BjABswkIoDmyoRJAEohuZCamZNA--p-uRqJjRefED1eMrKSppabV2ugaqoFlieujTOE-a3VKib9aC-lFsmLalkwh9ctr_FZqS9H46rqGjGcOxtAXalo1jkMPGupVsE1W-xIH14wbPCYcgfldH9SH7X60462kxD8OFdHpvnnfAvjQnaE4QDqasT5ySpBRtck4GVxs2IRBt62-kOlzoI8lHapLdwIms-Gdt7z38E47ZE3afE4IIbobPGz7wGvjbi3z234ARvGQ4jREgPQb1NRYAEtZlrZNzR6N7ofXD8jF502tw-QWI_Ox0jFP5tynIiMp-hG25ecQ0s4MzPHFC0ZABPamgg3MS-UILl76gMDCHS5Te_JAXZoC1HnkETw5M217SaG5ISAU0F5qETMREfTjZR9E45MDhnw7uY1vo2lffRB3ei1QqGuLh0gUnVU7TUfFYwcOqV15sb0t1lMj0mmyG5v-_dE9H6dYtRKJARltmdfSmc1HisBewx75Xh5ChJQ1hiCEDaZ1wqFjsFJ6SrKgJ7C1N7vx6QKx8YXwFH7ePG2qG39leT5JKZnqAvi9fqc6x-YwfhSjbRKGZoj2o55Fd2fbwtK6CXpiW6AekT7PUcl_7ynTq-DaQ_Yc29WwtmgapcCRNpfcMsoqCD4giu1V3Sj5DQLglwuk1gAMcuV5fo8JpABu2_is83WZ_GJ1WWMUxyZGq6u-EGuZrP96Yewb7-zfnt2lao_LJg1ef5cqDTW7-0MS27wkmLiIi0e-PYvS-UfWVHg1oNbR-MHXMVEQ6gqNg08IgEyPDSFCUbf75HuMILN80bQNtSlFj6FR7uNKHr8sigvKI80k.5flOKKmeqYm0TamwROr8Nw"

const decrypted = await jose.compactDecrypt(
  fileEncrypted,
  jose.base64url.decode(shlinkPayload.key),
  {inflateRaw: async (bytes) => pako.inflateRaw(bytes)}
);

console.log(decrypted.protectedHeader.cty)
//application/smart-health-card

const decoded = JSON.parse(new TextDecoder().decode(decrypted.plaintext));
/*
{
  verifiableCredential: [
    "eyJ6aXAiOiJERUYiLCJhbGciOiJFUzI1NiIsImtpZCI6IjNLZmRnLVh3UC03Z1h5eXd0VWZVQUR3QnVtRE9QS01ReC1pRUxMMTFX..."
  ]
}
*/

Use Case Examples

Using SMART Health Links to share an interactive experience

While the SMART Health Links spec focuses on providing access to structured data, it’s often useful to share an interactive experience such as a web-based diagnostic portal where the SMART Health Links Receiving Application can review and add comments to a patient record. This can be accomplished in SMART Health Links with a manifest entry of type application/fhir+json that provides a FHIR Endpoint resource where:

• name describes the interactive experience with sufficient detail for the Receiving User to decide whether to engage
• connectionType is {"system": "https://smarthealthit.org", "code": "shl-interactive-experience"}
• address is the URI for the interactive experience
• period optionally documents the window of time when the interactive experience is available

For example, the manifest for an SMART Health Links that offers the user the opportunity to “Review a case” might include a application/fhir+json entry with:

{
  "resourceType": "Endpoint",
  "status": "active",
  "name": "Review and comment on Alice's case in ACME Medical Diagnostic Portal",
  "address": "https://interact.example.org/case-id/521039c3-4bb9-45bd-8271-6001d2f4dea9",
  "period": {"end": "2022-10-20T12:30:00Z"},
  "connectionType": {"system": "https://smarthealthit.org", "code": "shl-interactive-experience"},
  "payloadType": [{"system": "http://terminology.hl7.org/CodeSystem/endpoint-payload-type", "code": "none"}],
}

Notes:

• There is no perfect FHIR resource for documenting an interactive experience URL. Endpoint and DocumentReference are both plausible candidates, and we recommend Endpoint here because DocumentReference is designed for static payloads.
• If the only content being shared via SMART Health Links is a single interactive experience, implementers might consider sharing the interactive experience URL directly, instead of through SMART Health Links. However, since SMART Health Links provides a consistent pattern that users and tools can recognize, starting with SMART Health Links provides a foundation to support future expansion.

“Upgrading” from SMART Health Links to a consumer-mediated SMART on FHIR Connection

In addition to providing direct access to a pre-configured data set, SMART Health Linkss can include information to help establish a consumer-mediated SMART on FHIR connection to the data source. This can be accomplished with a SMART Health Links manifest entry of type application/fhir+json that provides a FHIR Endpoint resource where:

• name describes the SMART on FHIR endpoint with sufficient detail for the Receiving User to decide whether to connect
• connectionType is {"system": "http://terminology.hl7.org/CodeSystem/restful-security-service", "code": "SMART-on-FHIR"}
• address is the FHIR API base URL of the server that supports SMART App Launch

For example, the manifest for an SMART Health Links from Labs-R-Us might include a application/fhir+json entry with:

{
  "resourceType": "Endpoint",
  "status": "active",
  "name": "Labs-R-Us Application Access",
  "address": "https://fhir.example.org",
  "connectionType": {"system": "http://terminology.hl7.org/CodeSystem/restful-security-service", "code": "SMART-on-FHIR"},
  "payloadType": [{"system": "http://terminology.hl7.org/CodeSystem/endpoint-payload-type", "code": "none"}],
}

Notes:

• Clients may need to pre-register with the SMART App Launch enabled service before they can request a connection. A client might compare "address" against an internal database to determine whether it can connect, retrieve {address}/.well-known/smart-configuration to determine whether the Dynamic Client Registration Protocol is available or come up with another way to determine connectivity in order to inform the user of how they can act on the SMART Health Links.

• This capability will only work in cases where the user receiving the SMART Health Links is authorized to approve SMART App Launch requests; other recipients might see the Endpoint but would be unable to complete a SMART App Launch