Verifiable Health Links
1.0.0-comment - ballot
Verifiable Health Links, published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 1.0.0-comment built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/IHE/ITI.VHL/ and changes regularly. See the Directory of published versions
Note on Transaction Optionality: This transaction is REQUIRED (R) for both the VHL Holder (Initiator) and the VHL Receiver (Responder). Optional behaviors within this transaction, such as the VC Enveloped VHL Option, are defined as actor options for this transaction.
The Provide VHL transaction enables a VHL Holder to transmit a Verifiable Health Link (VHL) to a VHL Receiver. The VHL serves as a signed authorization mechanism that allows the Receiver to subsequently retrieve one or more health documents from a VHL Sharer (via ITI-YY5).
The VHL is transmitted as a QR code containing an HCERT-encoded payload with the HC1: prefix, OR — when the VHL Sharer supports the VC Enveloped VHL Option at ITI-YY3 — as a signed W3C Verifiable Credential (application/vc). VHL Receivers scan the QR code or parse the VC to extract the VHL payload for subsequent document retrieval.
Table 2:3.YY4.2-1: Actor Roles
| Actor | Role |
|---|---|
| VHL Holder | Provide VHL |
| VHL Receiver | Receive VHL authorization mechanism |
QR Code Carrier:
VC Enveloped VHL Option (Optional):
DataIntegrityProofFigure 2:3.YY4.4-1: Provide VHL Interaction Diagram
The Provide VHL transaction enables a VHL Holder to transmit a Verifiable Health Link (VHL) to a VHL Receiver. The VHL serves as a signed authorization mechanism that allows the Receiver to subsequently retrieve one or more health documents from a VHL Sharer.
Depending on the use case, the VHL MAY be rendered or transmitted using formats such as QR code or deep link (HTTPS URL).
A VHL Holder initiates the Provide VHL transaction when:
Before transmitting, the VHL Holder SHALL:
QR Code Transmission:
Verifiable Credential Transmission, where the supports the VC Enveloped VHL Option:
validUntil not passed, DataIntegrityProof intact)application/vc document to the VHL Receiver via an agreed channel (HTTPS, email attachment, file transfer, or NFC)The VHL Holder MAY:
The VHL payload structure is defined in ITI-YY3 and aligns with the SMART Health Links specification.
QR Code Transmission
The VHL is transmitted via QR code with the following characteristics:
HC1: prefixVerifiable Credential Transmission (VC Enveloped VHL)
When the VHL Sharer supports the VC Enveloped VHL Option, the VHL MAY alternatively be transmitted as a signed JSON-LD Verifiable Credential:
application/vc; some channels — a file on removable media, or a blob read from NFC — carry none, in which case the document is identified by its contentvhlink: URI at credentialSubject.id — the same payload the QR carrier places at HCERT claim key 5, though encoded as a URI rather than as a CBOR map — and is signed by the VHL Sharer with a DataIntegrityProof (cryptosuite per Cryptographic Algorithm Selection)The VHL Receiver SHALL be capable of receiving a Verifiable Health Link (VHL) from a VHL Holder through a supported transport mechanism (e.g., QR code scan, direct URL, or digital message).
Upon receipt, the Receiver SHALL:
Receipt of the VHL may occur through direct user interaction (e.g., scanning a QR code) or automated channels, depending on the implementation context.
The VHL Receiver SHALL decode the received VHL using the appropriate path below. Upon receiving a VHL via QR code, the VHL Receiver SHALL perform the following 9-step decoding process. When the VHL is received as a Verifiable Credential (VC Enveloped VHL Option), see the VC Decoding section further below.
HC1: prefix (HCERT context identifier)HC1: prefix from the stringalg (algorithm): selected per Cryptographic Algorithm Selectionkid (key identifier): the identifier the trust framework derives from the DSC, matched against the verification methods in the trust listkid from CWT protected headeriss (issuer, claim key 1): ISO 3166-1 alpha-2 country code (optional)iat (issued at, claim key 6): timestamp in NumericDate formatexp (expiration, claim key 4): timestamp in NumericDate formathcert (health certificate, claim key -260): HCERT payload objectexp - reject if current time > expirationiat is not in the futurehcert claim (claim key -260), locate claim key 5url: manifest URL (required) - includes all mandatory FHIR search parameterskey: base64url-encoded decryption key, 43 characters (required). The VHL Receiver caches this key for the VHL session and uses it as the symmetric key for JWE dir/A256GCM decryption of document binaries retrieved via ITI-68; see ITI-YY5 Document Encryption.flag: flags such as "L" for long-term, "P" for passcode (optional). See ITI-YY3 Flagslabel: human-readable description (optional)exp: expiration timestamp in seconds since epoch (optional)v: version number (optional)url field is present and is a valid HTTPS URLkey field is present and is 43 characters (base64url-encoded 32 bytes)exp (if present)flag value:
url contains expected manifest endpoint format with mandatory parametersVerifiable Credential Decoding (VC Enveloped VHL Option):
When the VHL is received as a Verifiable Credential instead of a QR code, the VHL Receiver SHALL instead:
application/vc. Where the channel carries no media type, the VHL Receiver SHALL identify the document by its content: a JSON object whose @context begins with https://www.w3.org/ns/credentials/v2. Reject if parsing fails or the document does not conform to the VC Data Model.proof.verificationMethod to the VHL Sharer's key via the trust list (same DSC/trust framework used for CWT verification), then verify the DataIntegrityProof per W3C Verifiable Credential Data Integrity 1.0. Reject if the proof is invalid or the issuer is untrusted.validUntil has passed or validFrom is in the future.vhlink: URI from credentialSubject.id, strip the vhlink:/ prefix, base64url-decode the remainder, and parse the result as the VHL payload. This yields the same payload the QR carrier conveys as a CBOR map at HCERT claim key 5, so validation proceeds as in step 9 of the QR code path; only the decoding differs.url, 43-character key, exp not passed, flag handling).The VHL Receiver then continues with Post-Decoding Actions below as in the QR code path.
Post-Decoding Actions:
After successfully decoding the VHL payload (from either QR code or VC), the VHL Receiver SHALL:
key parameter from the VHL payload is required to decrypt documents_id: The folder IDcode: Typically "folder"status: Typically "current"patient.identifier: Patient business identifier via FHIR chained search on the patient reference parameter, in system|value format. This is the same identifier the VHL Holder supplied as sourceIdentifier at ITI-YY3._include=List:item: (if VHL Sharer supports Include DocumentReference Option)https://vhl-sharer.example.org/List?_id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT&code=folder&status=current&patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123&_include=List:itemThe VHL Receiver MAY:
Decoding Example (QR Code with HCERT):
Input QR Code Content:
HC1:NCF3R0KLBBA...V8N8W.CE8WY
Step 1: Scan the QR code → HC1:NCF3R0KLBBA...V8N8W.CE8WY
Step 2: Verify and remove HC1: prefix → NCF3R0KLBBA...V8N8W.CE8WY
Step 3: Base45 decode → [compressed bytes]
Step 4: ZLIB/DEFLATE decompress → [CBOR bytes]
Step 5: Parse CBOR as CWT → Extract protected header (alg: ES256, kid: 8-byte SHA-256)
Step 6: Verify COSE signature using DSC from trust list based on kid
Step 7: Extract CWT claims:
- iss (claim 1): "US"
- iat (claim 6): 1704067200
- exp (claim 4): 1735689600
- hcert (claim -260): {...}
Step 8: Within hcert (claim -260), read claim key 5. It is a CBOR map with text keys,
which is the VHL payload itself — no prefix to strip and nothing to decode.
Where key 5 is instead a vhlink:/ string, as earlier drafts specified, strip
the prefix and base64url-decode it. Either way the payload is:
{
"url": "https://vhl-sharer.example.org/List?_id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT&code=folder&status=current&patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123&_include=List:item",
"key": "86F8LY5LlWAa1-OS_FgrTnYNqFHJP2ey5RSKLJBN9jk",
"flag": "LP",
"exp": 1735689600,
"label": "Patient Health Summary",
"v": 1
}
Step 9: Validate VHL payload fields (HTTPS url, 43-character key, exp not passed, flags)
Then, as Post-Decoding Actions: parse the manifest URL to extract the FHIR search
parameters, cache the key, and prepare for ITI-YY5 Retrieve Manifest.
Manifest URL Parsing:
The manifest URL from the VHL payload contains all parameters needed for Retrieve Manifest [ITI-YY5]:
URL: https://vhl-sharer.example.org/List?_id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT&code=folder&status=current&patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123&_include=List:item
Parsed FHIR Search Parameters (for ITI-YY5):
- _id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT
- code=folder
- status=current
- patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123
- _include=List:item (if present, indicates VHL Sharer supports Include DocumentReference Option)
Error Handling:
If QR code scanning or decoding fails:
The VHL Receiver SHALL:
If signature verification fails:
If the CWT exp claim has passed, the signed token is no longer valid:
The VHL Receiver MAY provide an optional acknowledgment to the VHL Holder confirming receipt and validation. This is transmission-mechanism dependent.
For transmission mechanisms supporting bidirectional communication, the response MAY include the elements listed in Table 2:3.YY4.4.2.2-1.
Table 2:3.YY4.4.2.2-1: Provide VHL Acknowledgment Elements
| Element | Cardinality | Description |
|---|---|---|
| Acknowledgment | [0..1] | Confirmation VHL received and validated |
| Receipt Identifier | [0..1] | Unique identifier for receipt transaction |
| Receiver Identifier | [0..1] | Identifier of VHL Receiver organization |
| Timestamp | [0..1] | ISO 8601 timestamp of receipt |
VHL Receiver:
VHL Holder:
Where the VHL is transmitted over HTTP between the two actors, the secure channel requirements in Volume 1 Section XX.5.2 Secure Channel Requirements apply. Several of the transmission mechanisms this transaction allows are not HTTP exchanges — a printed QR code, or one displayed on a screen — and for those the VHL Holder is responsible for presenting the VHL only to an intended VHL Receiver, since no transport control stands between them.
key, the optional label, and a manifest URL that itself contains the patient business identifier — so the VHL as a whole is sensitive, and warrants the handling given to a credential rather than to a link. See ITI-YY3 Encryption Key Security and ITI-YY5 Privacy of Request Metadata.key.exp claim bounds the validity of the signed token, and rejecting a VHL whose CWT has expired is required at 2:3.YY4.4.1.3 Expected Actions. The VHL payload exp is a hint to the VHL Receiver per SMART Health Links; what denies access is deactivation of the VHL by the , which a VHL Receiver observes as 404 Not Found at ITI-YY5QR Code Characteristics:
Best Practices:
When the VHL is carried as a Verifiable Credential:
key and SHOULD be treated as sensitive