Verifiable Health Link
0.0.2-current - ci-build International flag

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-13 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

UseNameScopeCardinalityTypeBindingDocumentation
INsourceIdentifier1..1Identifier

An identifier for the patient. Required if 'bundle' is not provided.

INexp0..1integer

Optional. Number representing expiration time in Epoch seconds, as a hint to help the SHL Receiving Application determine if this QR is stale.

INflag0..1string

Optional. String created by concatenating single-character flags in alphabetical order. L (long-term use), P (Passcode required)

INlabel0..1string

Optional. String no longer than 80 characters that provides a short description of the data behind the SHLink.

INpasscode0..1string

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.

OUTqrcode1..1Binary

A Binary resource containing the QR code image (PNG or SVG format) that encodes the VHL as an HCERT/CWT structure.

VHL Payload Construction:

  1. Generate a unique folder ID with 256-bit entropy to serve as the List resource identifier
  2. Generate a 32-byte (256-bit) random encryption key, base64url-encode it (resulting in 43 characters) - this is the 'key' parameter
  3. 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]
  4. 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)
  5. 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