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 Sharer (Responder). Optional behaviors within this transaction, such as the VC Enveloped VHL Option, are defined as actor options for this transaction.
The Generate VHL transaction enables a VHL Holder to request a Verifiable Health Link (VHL) from a VHL Sharer for a Patient identified by a business identifier (e.g., MRN, passport number, national ID). The VHL Sharer locates the Patient, authorizes the caller, assembles a folder of available health documents, and returns a VHL that the VHL Holder can subsequently transmit to a VHL Receiver via ITI-YY4 Provide VHL for downstream document retrieval via ITI-YY5 Retrieve Manifest.
The VHL payload conforms to the SMART Health Links payload format and carries the manifest URL, a symmetric decryption key, and optional metadata (expiration, flags, label). By default the VHL is returned as a QR code encoded as an HCERT/CWT structure per the WHO SMART Trust HCERT specification. When the VHL Sharer supports the VC Enveloped VHL Carrier Option, the caller MAY instead request the VHL as a signed W3C Verifiable Credential (application/vc).
The transaction also supports optional passcode protection, purpose-of-use authorization metadata (which MAY populate an IHE PCF Consent.provision.purpose when the VHL Sharer is grouped with a Consent Recorder/Registry), and the Sign Manifest Request Option (OAuth with SSRAA) for downstream authenticated manifest retrieval.
Table 2:3.YY3.2-1: Actor Roles
| Actor | Role |
|---|---|
| VHL Holder | Request that a VHL authorization mechanism be issued |
| VHL Sharer | Generate a VHL Authorization Mechanism Based on Query Parameters |
QR Code Carrier (format=qrcode):
OAuth with SSRAA (Optional):
VC Enveloped VHL Option (Optional):
DataIntegrityProofFigure 2:3.YY3.4-1: Generate VHL Interaction Diagram
This message is implemented as an HTTP POST operation from the client app used by the VHL Holder to the VHL Sharer using the FHIR $generate-vhl operation described in 2:3.YY3.4.1.2 Message Semantics.
A VHL Holder initiates a request to a VHL Sharer to generate a Verifiable Health Link (VHL) that references one or more health documents. The resulting VHL allows the Holder to subsequently share access to those documents with a VHL Receiver. The Holder MAY include optional parameters to constrain or protect the issued VHL-such as defining an expiration period, scoping which documents are included, or requiring a passcode for retrieval. These parameters guide the Sharer's issuance of the VHL and influence the conditions under which the associated documents may be accessed.
Preconditions:
The Generate VHL message is a FHIR operation request as defined in FHIR (http://hl7.org/fhir/operations.html) with the $generate-vhl operation definition.
The operation affects the state of the VHL Sharer, so it is invoked by HTTP POST as defined in FHIR (http://hl7.org/fhir/operations.html#request).
The name of the operation is $generate-vhl, and it is applied to the FHIR Patient resource type.
The URL for this operation is: [base]/Patient/$generate-vhl
Where [base] is the base URL of the VHL Sharer.
The Generate VHL message is performed by an HTTP POST command shown below:
POST [base]/Patient/$generate-vhl
Content-Type: application/x-www-form-urlencoded
sourceIdentifier=[token]{&exp=[positiveInt]}{&flag=[string]}{&label=[string]}{&passcode=[string]}{&purposeOfUse=[token]}{&format=[token]}
The parameters MAY equally be supplied as a FHIR Parameters resource in the request body.
Each purposeOfUse value is serialized in FHIR token form (system|code, e.g., http://terminology.hl7.org/CodeSystem/v3-ActReason|TREAT) and MAY repeat.
Note: By default the operation generates a QR code containing the VHL encoded as an HCERT/CWT structure. When the VHL Sharer supports the VC Enveloped VHL Option the caller MAY set format=vc to request the VHL as a signed Verifiable Credential instead. See Output Carrier Options below for both carrier definitions.
Table 2:3.YY3.4.1.2-1: $generate-vhl Message HTTP Query Parameters
| Query Parameter Name | Cardinality | Search Type | Description |
|---|---|---|---|
| sourceIdentifier | [1..1] | token | A FHIR Identifier (business identifier — e.g., MRN, passport number, national ID) that the VHL Sharer uses to locate the Patient record and that Patient's documents. |
| exp | [0..1] | positiveInt | Optional. Number representing expiration time in Epoch seconds. |
| flag | [0..1] | string | Optional. String created by concatenating single-character flags in alphabetical order. L (long-term use), P (Passcode required). See Flags. |
| label | [0..1] | string | Optional. String no longer than 80 characters that provides a short description of the data behind the VHL. |
| passcode | [0..1] | string | Optional. User-supplied passcode for passcode-protected VHLs. The 'P' flag SHALL be included in the flag parameter when a passcode is set. |
| purposeOfUse | [0..*] | token | Optional. Purpose(s) of use the VHL Holder is authorizing for this share, bound (extensible) to PurposeOfUse (e.g., TREAT, HPAYMT, HRESCH). Serialized as FHIR system|code. See Purpose of Use Handling. |
| format | [0..1] | token | Optional. Requested carrier for the returned VHL. Allowed values: qrcode (default) or vc. vc requires the VHL Sharer to support the VC Enveloped VHL Carrier Option; if unsupported, the VHL Sharer SHALL return an OperationOutcome error. See Output Carrier Options below. |
Flags
This profile defines two flags, listed in Table 2:3.YY3.4.1.2-2:
Table 2:3.YY3.4.1.2-2: VHL Flags
| Flag | Meaning |
|---|---|
| L | Long-term use. The folder referenced by the VHL is expected to remain available and MAY change over time |
| P | Passcode required. The VHL Receiver SHALL supply the passcode when retrieving the manifest — see ITI-YY5 |
Flags are concatenated in alphabetical order, so a VHL that is both long-term and passcode-protected carries LP.
Note on the SHL
Uflag. The SMART Health Links specification defines aUflag indicating that the link resolves directly to a single file, which the receiver retrieves without a manifest request. This profile does not defineU, and a VHL Sharer SHALL NOT set it.A VHL always references a folder identified by a folder ID with 256-bit entropy, and access to its contents is always mediated by Retrieve Manifest [ITI-YY5]. That transaction is where the VHL Sharer authenticates the VHL Receiver against the trust network, validates the passcode where one is set, and applies any consent-based filtering. The folder ID itself is the authorization mechanism for the VHL. A direct-file link would bypass all of these, and the resulting artifact would not be verifiable in the sense this profile requires.
Sharing a single document is supported by generating a VHL for a folder containing one entry; no separate mechanism is needed.
The format request parameter selects one of two carriers for the returned VHL. Both carriers convey the same VHL payload (manifest URL, decryption key, flags, label, expiration, optional extension); they differ only in encoding, signature format, and the trust chain used for verification. On a successful response, exactly one of the response output parameters qrcode or verifiableCredential (see 2:3.YY3.4.2.2 Message Semantics) SHALL be populated; on failure, the response is an OperationOutcome with neither output parameter populated.
QR Code Carrier (Default — format=qrcode)
The default carrier when format is omitted or set to qrcode. The VHL payload is embedded in an HCERT structure at claim key 5 per the WHO SMART Trust HCERT specification, signed as a CWT, and rendered as a QR code with the HC1: prefix. The VHL Receiver verifies the CWT signature against the trust list. See 2:3.YY3.4.1.3 Expected Actions for the full VHL Payload Construction and HCERT/CWT encoding steps, including a worked example.
VC Enveloped VHL Carrier (Option — format=vc)
Optional carrier. Available only when the VHL Sharer supports the VC Enveloped VHL Option (see Volume 1 Section 1:XX.2.6 VC Enveloped VHL Option); if requested but unsupported, the VHL Sharer SHALL return an OperationOutcome error. The same VHL payload is carried as the credentialSubject.id of a JSON-LD W3C Verifiable Credential (VC Data Model v2) with an embedded DataIntegrityProof (VC Data Integrity 1.0) signed by the VHL Sharer using its trust-network key — no new trust framework is introduced. See 2:3.YY3.4.1.3 Expected Actions for the full construction steps and a worked example.
The VHL Sharer SHALL generate a Verifiable Health Link (VHL) to be issued to a VHL Holder.
The Sharer SHALL conduct all necessary tasks to prepare the content referenced by the VHL. These tasks MAY be further defined by applicable content profiles or implementation guides, and MAY include:
Once content preparation is complete, the Sharer SHALL construct the VHL payload and sign it to produce a cryptographically verifiable authorization mechanism.
Optional behaviors:
Based on the requested format, the VHL Sharer generates the VHL as either a QR code (HCERT/CWT-encoded per the WHO SMART Trust HCERT specification, with the VHL payload embedded at claim key 5) or a Verifiable Credential (JSON-LD per the W3C VC Data Model v2, with the VHL payload carried as credentialSubject.id). Both carriers share the same VHL payload construction.
The generation process is as follows:
VHL Payload Construction
The VHL payload SHALL be constructed in alignment with the SMART Health Links specification. The structure described in the steps below is also recorded as the VHL Payload logical model. The VHL Sharer SHALL:
Generate a unique folder ID with 256-bit entropy to serve as the List resource identifier
Generate a 32-byte (256-bit) random encryption key, base64url-encode it (resulting in 43 characters)—this is the key parameter. The VHL Receiver uses this key to decrypt document binaries retrieved via ITI-68; see ITI-YY5 Document Encryption.
[base]/List?_id=[folder-id]&code=folder&status=current&patient.identifier=[sourceIdentifier-system|value]&_include=List:item
[base]/List?_id=[folder-id]&code=folder&status=current&patient.identifier=[sourceIdentifier-system|value]
Note: This profile requires the manifest URL to include _id, code, status, and patient.identifier (chained search on the patient reference parameter, in system|value form). IHE MHD ITI-66 Find Document Lists already requires the Document Consumer to include code, status, and patient/patient.identifier, and requires the Document Responder to support _id — this profile additionally requires _id to be present in every VHL manifest URL, since the folder ID is the primary authorization mechanism for the VHL (see ITI-YY5 Section 2:3.YY5.4.1.2 FHIR Search Parameters where _id is marked [1..1]). _include=List:item is added only when the VHL Sharer supports the Include DocumentReference Option.
url: the manifest URL from step 3key: the base64url-encoded encryption key from step 2 (43 characters). Used by the VHL Receiver as the symmetric key for JWE dir/A256GCM decryption of document binaries; see ITI-YY5 Document Encryption.exp: (optional) expiration time in Epoch seconds, as a hint to help the VHL Receiver determine if this VHL is staleflag: (optional) flags string — L for long-term, P for passcode, LP for both. See Flagslabel: (optional) description string (max 80 characters)v: version number (defaults to 1)extension: (conditional) object containing implementation-defined extensions. Required when the VHL Sharer claims the Sign Manifest Request Option (OAuth with SSRAA), in which case it SHALL include:
fhirBaseUrl: (conditional) the FHIR base URL of the VHL Sharer (e.g., https://vhl-sharer.example.org). This enables the VHL Receiver to perform UDAP Discovery (per Section 2 of the HL7 Security for Scalable Registration, Authentication, and Authorization IG) and Dynamic Client Registration (per Section 3) with the VHL Sharer before making an authenticated manifest request via ITI-YY5.If the VHL Sharer does NOT claim that option, extension.fhirBaseUrl SHALL NOT be present in the VHL payload, to avoid misleading VHL Receivers into attempting UDAP Discovery unnecessarily.
The payload object from step 4 is then serialized for the requested carrier. The payload is the same in both cases; only its encoding differs:
format=qrcode (HCERT/CWT carrier): the payload is carried at HCERT claim key 5 as a CBOR map with text keys, conforming to the VHL Payload logical model. See QR Code Generation below.format=vc (VC Enveloped VHL Option): the payload is minified, base64url-encoded, and prefixed with vhlink:/ to form a URI. See VC Enveloped VHL Carrier below.Example VHL Construction:
The encoded values in steps 5b and 5c below are generated from the JSON in step 4. Any edit to the payload requires them to be regenerated; they are not to be modified by hand. They apply to the
format=vccarrier; theformat=qrcodecarrier uses the step 4 object directly, as a CBOR map.
// Step 4: VHL Payload JSON (SHL payload format, with OAuth with SSRAA extension)
{
"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",
"exp": 1735689600,
"flag": "LP",
"label": "Patient Health Summary",
"v": 1,
"extension": {
"fhirBaseUrl": "https://vhl-sharer.example.org"
}
}
// Step 5 (format=vc only): Minify, Base64url-encode, and prefix with vhlink:/
// Step 5a – Minified JSON:
{"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","exp":1735689600,"flag":"LP","label":"Patient Health Summary","v":1,"extension":{"fhirBaseUrl":"https://vhl-sharer.example.org"}}
// Step 5b – Base64url-encoded:
eyJ1cmwiOiJodHRwczovL3ZobC1zaGFyZXIuZXhhbXBsZS5vcmcvTGlzdD9faWQ9YWJjMTIzZGVmNDU2JmNvZGU9Zm9sZGVyJnN0YXR1cz1jdXJyZW50JnBhdGllbnQuaWRlbnRpZmllcj11cm46b2lkOjIuMTYuODQwLjEuMTEzODgzLjIuNC42LjN8UEFTU1BPUlQxMjMmX2luY2x1ZGU9TGlzdDppdGVtIiwia2V5IjoiODZGOExZNUxsV0FhMS1PU19GZ3JUbllOcUZISlAyZXk1UlNLTEpCTjlqayIsImV4cCI6MTczNTY4OTYwMCwiZmxhZyI6IkxQIiwibGFiZWwiOiJQYXRpZW50IEhlYWx0aCBTdW1tYXJ5IiwidiI6MSwiZXh0ZW5zaW9uIjp7ImZoaXJCYXNlVXJsIjoiaHR0cHM6Ly92aGwtc2hhcmVyLmV4YW1wbGUub3JnIn19
// Step 5c – Final VHL link (prefixed with vhlink:/):
vhlink:/eyJ1cmwiOiJodHRwczovL3ZobC1zaGFyZXIuZXhhbXBsZS5vcmcvTGlzdD9faWQ9YWJjMTIzZGVmNDU2JmNvZGU9Zm9sZGVyJnN0YXR1cz1jdXJyZW50JnBhdGllbnQuaWRlbnRpZmllcj11cm46b2lkOjIuMTYuODQwLjEuMTEzODgzLjIuNC42LjN8UEFTU1BPUlQxMjMmX2luY2x1ZGU9TGlzdDppdGVtIiwia2V5IjoiODZGOExZNUxsV0FhMS1PU19GZ3JUbllOcUZISlAyZXk1UlNLTEpCTjlqayIsImV4cCI6MTczNTY4OTYwMCwiZmxhZyI6IkxQIiwibGFiZWwiOiJQYXRpZW50IEhlYWx0aCBTdW1tYXJ5IiwidiI6MSwiZXh0ZW5zaW9uIjp7ImZoaXJCYXNlVXJsIjoiaHR0cHM6Ly92aGwtc2hhcmVyLmV4YW1wbGUub3JnIn19
// NOTE: extension.fhirBaseUrl is only present when the VHL Sharer claims the OAuth with SSRAA option
// The vhlink: URI (step 5c) is used as credentialSubject.id under the VC Enveloped VHL Option.
// For format=qrcode the step 4 object is placed directly at HCERT claim key 5 as a CBOR map,
// with none of the encoding in step 5 applied (see QR Code Generation below).
QR Code Generation (HCERT/CWT Encoding) — format=qrcode
After constructing the VHL payload (steps 1–4 above), the VHL Sharer SHALL encode it within an HCERT structure per the WHO SMART Trust specification, placing the payload at HCERT claim key 5 as a CBOR map with text keys, then generate the QR code per the HCERT Specification.
The CWT is signed with the VHL Sharer's trust network private key — the key whose public half and certificate chain it published through Submit PKI Material with DID [ITI-YY1]. The COSE kid header identifies which verification method was used, so the VHL Receiver can resolve the matching key from the trust list it retrieved via Retrieve Trust List with DID [ITI-YY2].
Example HCERT/CWT Structure:
The CWT is signed as a COSE single-signer structure (COSE_Sign1). CBOR is shown as JSON for readability; the protected header and payload are CBOR byte strings on the wire.
// COSE_Sign1
[
// 1. protected header — signed
{
"1": -7, // alg: ES256
"4": "R2hT8kLm4Qs=" // kid: which key signed this
},
// 2. unprotected header — NOT signed
{},
// 3. payload — the CWT claims, signed
{
"1": "US", // iss: issuer country code
"4": 1735689600, // exp: expiration timestamp
"6": 1704067200, // iat: issued at timestamp
"-260": { // hcert: health certificate claim
"5": { // VHL: the payload as a CBOR map with text keys
"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",
"exp": 1735689600, // integer, not text
"flag": "LP",
"label": "Patient Health Summary",
"v": 1, // integer, not text
"extension": { // only under the OAuth with SSRAA option
"fhirBaseUrl": "https://vhl-sharer.example.org"
}
}
}
},
// 4. signature over the Sig_structure below
"MEUCIQDVJHCENivQvdeQJcNFZoucpkrSK_ZlEvwcikhQRR7r8wIgfkaKfg8cYA6CUPbu2lJZEhEVGWpeMcYwDrdPBhPVinM"
]
What the signature covers. The signature is computed over the COSE Sig_structure, not over the COSE_Sign1 array directly:
[
"Signature1", // context
h'a2012604...', // the serialized protected header (alg and kid)
h'', // external_aad — empty for this profile
h'a4011b62...' // the serialized payload (the CWT claims, including HCERT claim 5)
]
So the VHL payload and the alg and kid that describe how to verify it are all covered. The unprotected header is not, so nothing a VHL Receiver relies on may be placed there.
Resolving the key. The kid is the key identifier the trust framework derives from the certificate, and it is also the fragment of the verification method that holds that key — here did:web:vhl-sharer.example.org#R2hT8kLm4Qs= — a verification method in the VHL Sharer's DID Document, published through ITI-YY1 and obtained by the VHL Receiver in the trust list it retrieves through ITI-YY2. It is the same key the VC carrier signs with below, so both carriers verify against one entry in the trust list.
// The signed COSE_Sign1 is then zlib-compressed, Base45-encoded and prefixed:
HC1:NCF3R0KLBBA...V8N8W.CE8WY
VC Envelope Generation (Option — format=vc)
When format=vc is requested and the VHL Sharer supports the VC Enveloped VHL Option, the VHL Sharer SHALL construct a JSON-LD document per the W3C VC Data Model v2 with an embedded proof of type DataIntegrityProof per the W3C VC Data Integrity 1.0 specification (cryptosuite selected per the central Cryptographic Algorithm Selection). The issuer SHALL identify the VHL Sharer using a key from the same trust network used for HCERT/CWT signatures — no new trust framework is introduced.
The credentialSubject.id SHALL be the vhlink: URI produced by step 5c. The two carriers convey the same payload fields in different encodings — this one a base64url-encoded URI, the QR carrier a CBOR map at HCERT claim key 5 — so a VHL Receiver decodes them differently and arrives at the same payload object.
The payload is carried as a single URI rather than as members of credentialSubject for two reasons. id is a core term of the VC Data Model, so it survives JSON-LD expansion under the base context alone; payload field names such as url and key are not defined by any context this profile publishes, and JSON-LD expansion discards undefined terms, which under an RDF-canonicalizing cryptosuite such as ecdsa-rdfc-2019 would leave them outside the signature while the credential still verified. Carrying them inside the URI also keeps the decryption key out of a named, indexable field, consistent with the treatment of that key at ITI-YY5. Note that id is itself optional in the VC Data Model; the structured alternative is available to this profile if it publishes and maintains a JSON-LD context defining those terms.
The VC is delivered to the VHL Holder and subsequently transmitted to the VHL Receiver per ITI-YY4 Provide VHL.
Example VC carrying the VHL payload:
{
"@context": ["https://www.w3.org/ns/credentials/v2"],
"type": ["VerifiableCredential"],
"issuer": "did:web:vhl-sharer.example.org",
"validFrom": "2024-01-01T00:00:00Z",
"validUntil": "2025-01-01T00:00:00Z",
"credentialSubject": {
"id": "vhlink:/eyJ1cmwiOiJodHRwczovL3ZobC1zaGFyZXIuZXhhbXBsZS5vcmcvTGlzdD9faWQ9YWJjMTIzZGVmNDU2JmNvZGU9Zm9sZGVyJnN0YXR1cz1jdXJyZW50JnBhdGllbnQuaWRlbnRpZmllcj11cm46b2lkOjIuMTYuODQwLjEuMTEzODgzLjIuNC42LjN8UEFTU1BPUlQxMjMmX2luY2x1ZGU9TGlzdDppdGVtIiwia2V5IjoiODZGOExZNUxsV0FhMS1PU19GZ3JUbllOcUZISlAyZXk1UlNLTEpCTjlqayIsImV4cCI6MTczNTY4OTYwMCwiZmxhZyI6IkxQIiwibGFiZWwiOiJQYXRpZW50IEhlYWx0aCBTdW1tYXJ5IiwidiI6MSwiZXh0ZW5zaW9uIjp7ImZoaXJCYXNlVXJsIjoiaHR0cHM6Ly92aGwtc2hhcmVyLmV4YW1wbGUub3JnIn19"
},
"proof": {
"type": "DataIntegrityProof",
"cryptosuite": "ecdsa-rdfc-2019",
"created": "2024-01-01T00:00:00Z",
"verificationMethod": "did:web:vhl-sharer.example.org#R2hT8kLm4Qs=",
"proofPurpose": "assertionMethod",
"proofValue": "z3FD9sJ8kL2m9pQ7rT4vW5xY6zAb3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX4yZ"
}
}
Handling Notes
The following handling rules apply within the steps above:
sourceIdentifier Validation — The VHL Sharer SHALL parse sourceIdentifier as a FHIR Identifier in system|value form, resolve it to a known Patient, authorize the caller, and echo the exact system|value into the manifest URL as patient.identifier (never substituting Patient.id). In patient-constrained contexts (e.g., SMART launch/patient scope), mismatches with the patient-in-context SHALL be rejected with 403. Other failures return OperationOutcome with 400 / 404 / 403 as appropriate.
Purpose of Use Handling (if provided) — The VHL Sharer SHALL validate each purposeOfUse value against PurposeOfUse (extensible binding) and persist the value(s) against the folder ID for downstream enforcement at ITI-YY5. When grouped with an IHE PCF Consent Recorder or Consent Registry, the persisted value(s) SHALL populate Consent.provision.purpose. purposeOfUse value(s) SHALL NOT be embedded in the QR code, VC, or VHL payload — they are share metadata held by the VHL Sharer, not content consumed by the VHL Receiver. The VHL Receiver's own self-issued credential at ITI-YY5 is a separate document and MAY state a purpose of use the VHL Receiver asserts for itself; the VHL Sharer is what compares the two.
Passcode Handling (if provided) — The VHL Sharer SHALL hash the passcode with a strong one-way function (e.g., bcrypt, Argon2, PBKDF2), store the hash against the folder ID for ITI-YY5 validation, and set the P flag in the VHL payload. The plaintext passcode SHALL NOT appear in the VHL URL, QR code, or VC, and SHALL NOT be stored by the VHL Sharer; the VHL Holder retains it for out-of-band sharing with the VHL Receiver.
The VHL Sharer returns failure, or generates and returns the VHL as a QR code encoded as an HCERT/CWT structure or, under the VC Enveloped VHL Option, as a Verifiable Credential.
This message shall be sent when a request initiated by the VHL Holder has been processed successfully.
See ITI TF-2: Appendix Z.6 for more details on response format handling.
The response message is a FHIR operation response (http://hl7.org/fhir/operations.html#response).
On failure, the response message is an HTTP status code of 4xx or 5xx indicating an error, and an OperationOutcome Resource shall be returned with details.
Success Response:
The response SHALL include exactly one of the output parameters listed in Table 2:3.YY3.4.2.2-1, selected by the format input:
Table 2:3.YY3.4.2.2-1: $generate-vhl Output Parameters
| Parameter | Type | Cardinality | Description |
|---|---|---|---|
| qrcode | Binary | [0..1] | QR code image containing HCERT-encoded VHL. Populated when format=qrcode or when format is absent, as the default format. |
| verifiableCredential | Binary | [0..1] | A Verifiable Credential (application/vc) carrying the VHL. Populated when format=vc and the VHL Sharer supports the VC Enveloped VHL Carrier Option. |
QR Code Output:
HC1: prefixVerifiable Credential Output (VC Enveloped VHL Option only):
Content-Type: application/vccredentialSubject.id, in the base64url-encoded vhlink: form, since a JSON-LD id cannot be a CBOR mapDataIntegrityProof with its trust-network key (cryptosuite selected per Cryptographic Algorithm Selection)The VHL Holder SHALL:
format=vc was requestedThe VHL Holder MAY:
VHL generation is subject to the secure channel requirements in Volume 1 Section XX.5.2 Secure Channel Requirements.
The key travels inside the VHL, so it does not restrict access by anyone holding the VHL — a VHL Receiver is authenticated and authorized separately, at Retrieve Manifest [ITI-YY5]. What document encryption buys is a different separation: trust in whoever stores or transports a document is decoupled from trust in whoever is authorized to read it. A repository, CDN or cache serving an encrypted binary never holds the key and cannot read what it serves. This follows the SMART Health Links design, which likewise assumes the file server need not be trusted with the contents of the files.
L) VHLs, whose folder contents change over time while the key does not. What ends access is deactivation of the VHL by the VHL Sharer, after which Retrieve Manifest [ITI-YY5] returns 404 Not Found. The payload exp is not that control: SMART Health Links defines it as a hint to the receiving application, and a VHL Receiver holding a leaked VHL need not consult it. A VHL Sharer issuing an exp SHOULD therefore deactivate the VHL when that time passes, so that the hint and the enforced state agree.A passcode buys a separation of possession of the VHL from the ability to use it. The exposures this matters for are the ones QR Code Security names — a VHL photographed, screenshotted, printed and left behind, forwarded, or sitting in a camera roll or a chat history — in all of which the VHL travels without the VHL Holder's intent.
_include parameter SHOULD only be included if the VHL Sharer supports the Include DocumentReference OptionfhirBaseUrl field is used by the VHL Receiver to perform UDAP Discovery ({fhirBaseUrl}/.well-known/udap) and, if not already registered, Dynamic Client Registration with the VHL Sharer before initiating ITI-YY5fhirBaseUrl value is typically derivable from the url field (manifest URL) by stripping the path, but including it explicitly avoids ambiguity when the authorization server is hosted separatelykey and SHOULD be treated as sensitive.