# Patient-Shared Health Document via SMART Health Links
> **Status:** Draft
> **Version:** 0.6.0
## Introduction
This implementation guide defines a constrained profile of SMART Health Links (SHLinks) for patient-to-provider sharing of health data at the point of care. A patient presents a QR code; the provider's EHR scans it, downloads an encrypted FHIR Bundle, and stores it.
### Requirements
> 1. Patient app creates a SHLink pointing to any FHIR resources and a DocumentReference to a "Patient-Shared PDF". This PDF should include:
> - All available USCDI data or a summary of elements specified by IPS, as filtered/selected by the patient. (Discrete data shared in the PDF should also be offered as FHIR discrete data.)
> - Any additional information the patient wants to share.
>
> 2. The provider can scan the SHLink QR, resolve + decrypt the data, and store this information.
> - The EHR must be able to store at least one of the Patient-Shared PDF or any FHIR Resources and present them to users.
> - The EHR may also display, ingest, and use other content from the SHLink.
>
> 3. At no point in this flow does a patient need to sign into an EHR Portal.
>
> — *Kill the Clipboard Working Group, updated 2/18/2026 (originally 1/30/2025)*
### Scope
This IG defines:
1. SHLink payload constraints for patient-shared health data
2. A FHIR Bundle profile containing the patient summary, optional DocumentReference with PDF, and discrete FHIR resources
3. Requirements for patient apps (senders) and EHRs (receivers)
4. An optional App Attestation extension for provenance signaling
### Actors
| Actor | Role |
|-------|------|
| Patient App | Generates SHLink QR containing encrypted FHIR Bundle (discrete resources and/or PDF) |
| Patient | Presents QR to provider |
| Provider EHR | Scans QR, downloads and stores patient-shared data (FHIR resources and/or PDF) |
---
## Workflow
```
┌──────────────┐ ┌──────────────┐
│ Patient App │ │ Provider │
│ │ │ EHR │
│ 1. Generate │ 2. Present QR │ │
│ Bundle │ ─────────────────────────────────► │ 3. Scan QR │
│ + SHLink │ │ │
│ │ │ 4. Decode │
│ │ │ SHLink │
│ │ 5. HTTP GET (+recipient) │ │
│ │ ◄───────────────────────────────── │ │
│ │ │ │
│ │ 6. Encrypted payload │ │
│ │ ─────────────────────────────────► │ 7. Decrypt │
│ │ │ + Store │
│ 8. Audit log │ │ │
└──────────────┘ └──────────────┘
```
> **Try it:** A working prototype with a sample QR code is available at [pshd-shl.exe.xyz/prototype.html](https://pshd-shl.exe.xyz/prototype.html).
---
## SHLink Constraints
This IG profiles the [SMART Health Links specification](https://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/links-specification.html) with the following constraints.
### SHLink Payload (decoded)
```json
{
"url": "https://patient-app.example.com/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM",
"flag": "U",
"key": "rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q",
"exp": 1706745600,
"label": "Jessica Argonaut's health summary"
}
```
| Field | Cardinality | Constraint |
|-------|-------------|------------|
| `url` | 1..1 | Endpoint returning encrypted payload |
| `flag` | 1..1 | `U` (direct retrieval; this is the SHLink default) |
| `key` | 1..1 | Decryption key |
| `exp` | 1..1 | **Required.** Expiration timestamp. SHOULD be short-lived for sensitive data. |
| `label` | 0..1 | Human-readable description |
Patient Apps SHALL generate SHLinks with the `U` flag, meaning the link resolves directly to a single encrypted file without requiring a passcode. Since this is the default SHLink behavior, most implementations will already conform.
---
## Retrieval Protocol
With the `U` flag, the SHLink URL resolves directly to a single encrypted file (bypassing the manifest).
### Request
The EHR retrieves the encrypted payload via HTTP GET. The EHR **SHALL** supply a `recipient` query parameter identifying the requesting organization.
```http
GET https://patient-app.example.com/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM
?recipient=Verona+Health+System
```
| Parameter | Cardinality | Description |
|-----------|-------------|-------------|
| `recipient` | 1..1 | Organization name requesting access. Appropriate for display to patient in audit log. |
### Response
```http
HTTP/1.1 200 OK
Content-Type: application/jose
```
Body contains a JWE (JSON Web Encryption) compact serialization string.
### Decryption
Per the SHLink specification, files are encrypted using JWE with:
- `"alg": "dir"` (direct encryption with shared symmetric key)
- `"enc": "A256GCM"` (AES-256-GCM)
- `"cty": "application/fhir+json"` (content type of decrypted payload)
The EHR decrypts using the 32-byte `key` from the SHLink payload (base64url-decoded) to obtain the FHIR Bundle.
**Example JWE structure (compact serialization):**
```
eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiY3R5IjoiYXBwbGljYXRpb24vZmhpcitqc29uIn0
..
<IV>
.
<ciphertext>
.
<authentication tag>
```
The decrypted payload is a FHIR Bundle conforming to the PatientSharedBundle profile.
---
## FHIR Bundle Profile: PatientSharedBundle
The decrypted payload is a FHIR Bundle conforming to this profile.
**Canonical URL:** `https://cms.gov/fhir/StructureDefinition/patient-shared-bundle`
### Structure
```
Bundle (type: collection)
├── Patient (1..1)
├── DocumentReference (1..1) - PatientSharedDocumentReference profile
│ └── content.attachment - embedded PDF (base64)
└── [Additional FHIR resources]* (0..*)
```
The Bundle MUST contain a DocumentReference with embedded PDF. Discrete FHIR resources (e.g., Conditions, Medications, Observations) are optional but SHOULD be included when available.
### Constraints
| Element | Cardinality | Constraint |
|---------|-------------|------------|
| `type` | 1..1 | Fixed: `collection` |
| `timestamp` | 1..1 | When bundle was assembled |
| `entry` | 1..* | Minimum: Patient and a DocumentReference; discrete FHIR resources are optional |
| `entry:patient` | 1..1 | Patient resource |
| `entry:documentReference` | 1..1 | Conforms to PatientSharedDocumentReference |
> **Note:** Resources in this Bundle SHOULD NOT include `meta.profile`. Receivers SHALL NOT require `meta.profile` to be present.
### Example
```json
{
"resourceType": "Bundle",
"type": "collection",
"timestamp": "2026-01-30T12:00:00Z",
"entry": [
{
"fullUrl": "urn:uuid:b5e506f4-e14c-4e27-9543-4b8d1e1f3e2a",
"resource": {
"resourceType": "Patient",
"name": [{"given": ["Jessica"], "family": "Argonaut"}],
"birthDate": "1985-03-15",
"gender": "female"
}
},
{
"fullUrl": "urn:uuid:c7a2f8e1-3d4b-5c6a-9e8f-0a1b2c3d4e5f",
"resource": {
"resourceType": "DocumentReference",
"meta": {
"security": [{
"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
"code": "PATAST",
"display": "patient asserted"
}]
},
"status": "current",
"type": {
"coding": [{
"system": "http://loinc.org",
"code": "60591-5",
"display": "Patient summary Document"
}]
},
"category": [{
"coding": [{
"system": "https://cms.gov/fhir/CodeSystem/patient-shared-category",
"code": "patient-shared",
"display": "Patient-Shared"
}]
}],
"subject": {
"reference": "urn:uuid:b5e506f4-e14c-4e27-9543-4b8d1e1f3e2a"
},
"author": [{
"reference": "urn:uuid:b5e506f4-e14c-4e27-9543-4b8d1e1f3e2a"
}],
"date": "2026-01-30T12:00:00Z",
"description": "Patient-shared health summary",
"content": [{
"attachment": {
"contentType": "application/pdf",
"data": "JVBERi0xLjQKJeLjz9..."
}
}]
}
}
]
}
```
---
## DocumentReference Profile: PatientSharedDocumentReference
**Canonical URL:** `https://cms.gov/fhir/StructureDefinition/patient-shared-document-reference`
**Based on:** [US Core DocumentReference](http://hl7.org/fhir/us/core/StructureDefinition-us-core-documentreference.html)
This profile aligns with the US Core [Writing Clinical Notes](https://build.fhir.org/ig/HL7/US-Core/writing-clinical-notes.html) guidance for patient-asserted content.
### Constraints
| Element | Cardinality | Constraint |
|---------|-------------|------------|
| `meta.security` | 0..* | SHOULD include `PATAST` (patient asserted) from `http://terminology.hl7.org/CodeSystem/v3-ObservationValue` |
| `status` | 1..1 | Fixed: `current` |
| `type` | 1..1 | Fixed: LOINC `60591-5` (Patient summary Document) |
| `category` | 1..* | SHALL include `https://cms.gov/fhir/CodeSystem/patient-shared-category#patient-shared` |
| `subject` | 1..1 | Reference(Patient) in same Bundle |
| `author` | 1..* | SHALL include Reference(Patient) — the patient is the author/sharer |
| `date` | 1..1 | When document was shared |
| `content` | 1..1 | |
| `content.attachment.contentType` | 1..1 | `application/pdf` |
| `content.attachment.data` | 1..1 | Base64-encoded PDF |
> **Note:** This profile applies only when a PDF is included. The PatientSharedBundle does not require a DocumentReference; apps MAY share only discrete FHIR resources.
---
## Terminology
### CodeSystem: PatientSharedCategory
**Canonical URL:** `https://cms.gov/fhir/CodeSystem/patient-shared-category`
| Code | Display | Definition |
|------|---------|------------|
| `patient-shared` | Patient-Shared | Document shared by the patient via patient-mediated exchange |
```json
{
"resourceType": "CodeSystem",
"id": "patient-shared-category",
"url": "https://cms.gov/fhir/CodeSystem/patient-shared-category",
"version": "0.3.0",
"name": "PatientSharedCategory",
"title": "Patient-Shared Document Category",
"status": "draft",
"experimental": true,
"description": "Code indicating a document was shared by the patient via patient-mediated exchange such as SMART Health Links",
"caseSensitive": true,
"content": "complete",
"concept": [
{
"code": "patient-shared",
"display": "Patient-Shared",
"definition": "Document shared by the patient or their authorized representative via patient-mediated exchange"
}
]
}
```
---
## Conformance Requirements
### Patient App (Sender)
**SHALL:**
- Generate SHLink with `flag` = `U`
- Include `exp` (expiration) in SHLink payload
- Serve encrypted payload without requiring authentication
- Return encrypted FHIR Bundle conforming to PatientSharedBundle profile
- Include a DocumentReference with embedded PDF conforming to PatientSharedDocumentReference
- Accept `recipient` query parameter on retrieval endpoint
- Audit each SHLink access with recipient and timestamp
**SHOULD:**
- Set short-lived expiration for sensitive data
- Enable patient to view audit log of who accessed their SHLink
- Minimize IP geofencing to enable reasonable international use
- Include Patient resource with sufficient demographics for matching
- Include `meta.security` with `PATAST` on DocumentReference (when present)
**MAY:**
- Include discrete FHIR resources (medications, conditions, observations, etc.) in addition to the PDF
- Include an App Attestation extension (see [App Attestation](#app-attestation-optional))
### Provider EHR (Receiver)
**SHALL:**
- Scan and decode SHLink QR codes
- Supply `recipient` query parameter identifying requesting organization
- Decrypt payload using key from SHLink
- Parse PatientSharedBundle
- Store and present the Patient-Shared PDF to users
- Indicate patient-shared provenance in clinical UI
**SHALL NOT:**
- Require `meta.profile` to be present on any resource
- Block Bundle processing when App Attestation is absent or fails verification
**SHOULD:**
- Display patient demographics from Bundle for verification
- Support clinician review before filing to chart
- Display an error message when an expired SHLink is scanned
- Verify App Attestation when present and display provenance indicator to clinician
**MAY:**
- Store and display the PDF from the DocumentReference
- Parse and display discrete FHIR resources from Bundle
- Ingest discrete data into structured EHR fields
- Support both PDF and FHIR resource consumption
---
## App Attestation (Optional)
When a provider scans a patient's SHLink QR code, they have no way to know whether the Bundle was produced by a recognized health app or assembled by hand. This optional extension addresses that gap: a Patient App can include a signed attestation that tells the receiver "a known app participated in creating this Bundle."
**This is a provenance signal, not a content signature.** The distinction is deliberate:
- **Patient-supplied data has inherent trust limitations.** The patient controlled this data before sharing it. A cryptographic signature over the content would imply integrity guarantees that cannot actually be delivered — the patient could have modified values after the app generated them. A content signature would give providers false confidence, which is worse than no signature.
- **The right question is "did a known app participate?" not "is this data tamper-proof?"** This attestation answers that question honestly, without requiring apps to implement full payload signing or exposing PHI to signing infrastructure.
### Structure
The attestation is a signed JWT (compact JWS) placed in `Bundle.meta.extension`:
```json
{
"resourceType": "Bundle",
"meta": {
"extension": [{
"url": "https://cms.gov/fhir/StructureDefinition/app-attestation",
"valueString": "eyJhbGciOiJFUzI1NiIsImtpZCI6Ijk4..."
}]
},
"type": "collection",
"entry": [ "..." ]
}
```
### JWT Header
| Field | Value |
|-------|-------|
| `alg` | `ES256` |
| `kid` | Key ID matching a key in the issuer's JWKS |
### JWT Claims
All three claims are required. No other claims are defined.
| Claim | Description |
|-------|-------------|
| `iss` | App's canonical URL (e.g., `https://healthapp.example`). Must match a domain in the trust framework's app list. |
| `iat` | Unix timestamp (seconds since epoch) when the attestation was minted. |
| `jti` | UUID uniquely identifying this attestation. |
The JWT intentionally contains no PHI and no content hash. It does not include an `exp` claim — the SHLink's own `exp` field governs payload lifetime.
### Key Discovery
Receivers resolve the app's signing key via JWKS discovery at a well-known path under the `iss` URL:
```
GET {iss}/.well-known/jwks.json
```
The JWKS must contain the public key matching `kid` from the JWT header. Keys must be EC P-256 (`"kty": "EC"`, `"crv": "P-256"`).
Apps participating in the trust framework SHALL publish a JWKS document at this path. The JWKS MAY contain multiple keys to support rotation.
### Verification
1. Extract the JWS string from the `app-attestation` extension
2. Decode the JWT header and claims; extract `iss` and `kid`
3. Confirm `iss` appears in the trust framework's app list *(how this list is distributed and maintained is out of scope for this IG)*
4. Fetch `{iss}/.well-known/jwks.json`; locate the public key by `kid`
5. Verify the ES256 signature
If verification succeeds, the receiver MAY display a provenance indicator (e.g., "✓ Created with HealthApp — recognized by CMS trust framework"). Verification failure or absence of the extension **SHOULD NOT** block processing of the Bundle — this is an optional enhancement, not a gate.
---
## Security Considerations
### Encryption
Per the SHLink specification, files are encrypted using JSON Web Encryption (JWE) compact serialization:
| Parameter | Value |
|-----------|-------|
| `alg` | `dir` (direct encryption — key used directly, no key wrapping) |
| `enc` | `A256GCM` (AES-256-GCM authenticated encryption) |
| `cty` | `application/fhir+json` (content type of plaintext) |
The 32-byte symmetric key is embedded in the SHLink payload as a base64url-encoded URL fragment (43 characters). Transmitting the key as a URL fragment rather than a query parameter means it is not forwarded to servers or captured in server logs. Security relies on:
1. The key never being transmitted to the server separately
2. Physical control of the QR by the patient
### Expiration
The `exp` field is **required** in this profile. Apps SHOULD set short-lived expirations appropriate to the use case:
| Scenario | Suggested Expiration |
|----------|---------------------|
| In-person visit (QR on phone screen) | 5–15 minutes |
| Printed QR for scheduled appointment | 24–48 hours |
| Ongoing care relationship | Per patient preference |
### App Attestation Key Security
Apps that publish a JWKS for App Attestation SHOULD:
- Protect private keys using hardware security modules or equivalent key management infrastructure
- Rotate signing keys periodically and maintain multiple active keys in JWKS to support seamless rotation
- Revoke compromised keys promptly
### Audit
Patient Apps SHALL maintain audit logs of SHLink access including:
- Timestamp
- Recipient organization (from query parameter)
---
## References
- [SMART Health Links Specification (STU1)](https://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/links-specification.html)
- [US Core DocumentReference](http://hl7.org/fhir/us/core/StructureDefinition-us-core-documentreference.html)
- [US Core Writing Clinical Notes](https://build.fhir.org/ig/HL7/US-Core/writing-clinical-notes.html)
- [International Patient Summary (IPS)](http://hl7.org/fhir/uv/ips/)
- [USCDI v3](https://www.healthit.gov/isa/united-states-core-data-interoperability-uscdi)
Sign in via Google
Sign in via Facebook
Sign in via X(Twitter)
Sign in via GitHub
Sign in via Dropbox
Sign in with Wallet
Connect another wallet