Verifiable Health Link
0.0.2-current - ci-build

Verifiable Health Link, published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 0.0.2-current 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

## OperationDefinition: Generate VHL

Official URL: http://example.org/fhir/OperationDefinition/generate-vhl | Version: 0.0.2-current
Active as of 2026-03-12 | Computable Name: GenerateVHL

This operation generates a QR code containing a Verifiable Health Link (VHL) for transmission or display.

Input Parameters:

- sourceIdentifier: Patient identifier (required)
- exp: Expiration time in Epoch seconds (optional)
- flag: Single-character flags in alphabetical order - L (long-term use), P (Passcode required), U (direct file access) (optional)
- label: Short description up to 80 characters (optional)
- passcode: User-supplied passcode for passcode-protected VHLs (optional)

Output Generation:

- Returns a Binary resource containing the QR code image (PNG or SVG format) that encodes the VHL as an HCERT/CWT structure.
- The QR code embeds the full SHL payload including the manifest URL and decryption key for secure access to health documents.

### Parameters

Use | Name | Scope | Cardinality | Type | Binding | Documentation
IN | sourceIdentifier |  | 1..1 | Identifier |  | An identifier for the patient. Required if 'bundle' is not provided.
IN | exp |  | 0..1 | integer |  | Optional. Number representing expiration time in Epoch seconds, as a hint to help the SHL Receiving Application determine if this QR is stale.
IN | flag |  | 0..1 | string |  | Optional. String created by concatenating single-character flags in alphabetical order. L (long-term use), P (Passcode required)
IN | label |  | 0..1 | string |  | Optional. String no longer than 80 characters that provides a short description of the data behind the SHLink.
IN | passcode |  | 0..1 | string |  | Optional. User-supplied passcode for passcode-protected VHLs. If provided, the VHL Sharer SHALL securely hash and store this passcode for validation during manifest retrieval (ITI-YY5). The 'P' flag SHALL be included in the flag parameter when a passcode is set.
OUT | qrcode |  | 1..1 | Binary |  | A Binary resource containing the QR code image (PNG or SVG format) that encodes the VHL as an HCERT/CWT structure. VHL Payload Construction: 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 Construct the manifest URL as a query on the base List resource: If VHL Sharer supports Include DocumentReference Option: [base]/List?_id=[folder-id]&code=folder&status=current&patient.identifier=[patient-id]&_include=List:item If VHL Sharer does NOT support Include DocumentReference Option: [base]/List?_id=[folder-id]&code=folder&status=current&patient.identifier=[patient-id] Create the SHL payload as a JSON object with: url: the manifest URL from step 3 key: the base64url-encoded encryption key from step 2 (43 characters) exp: (optional) expiration time in Epoch seconds flag: (optional) flags string (e.g., 'P' for passcode, 'L' for long-term, 'U' for direct file access) label: (optional) description string (max 80 characters) v: version number (defaults to 1) extension: (conditional) object containing implementation-defined extensions. Required when the VHL Sharer supports the OAuth with SSRAA Option, in which case it SHALL include fhirBaseUrl (the FHIR base URL of the VHL Sharer, e.g., https://vhl-sharer.example.org) Minify the JSON payload, Base64url-encode it, and prefix with vhlink:/ QR Code Generation (HCERT/CWT Encoding): The VHL Sharer SHALL encode the VHL payload within an HCERT structure as per the [WHO SMART TRUST specification] (https://smart.who.int/trust/). The HCERT claim key SHALL be 5 for VHL. The QR code is then generated per the HCERT Specification. For complete HCERT specification, see: https://smart.who.int/trust/hcert_spec.html For HCERT logical model, see: https://smart.who.int/trust/StructureDefinition-HCert.html For SHL payload details, see: https://build.fhir.org/ig/HL7/smart-health-cards-and-links/links-specification.html#construct-a-smart-health-link-payload