Setting Up a Verifiable Credentials System for Patient Health Records

Verifiable Credentials (VCs) provide a cryptographically secure, privacy-preserving framework for managing digital identity and attestations. In healthcare, this enables patients to own and control their health data—such as vaccination records, lab results, or prescriptions—as portable, tamper-evident credentials. Unlike centralized databases, VCs are issued by trusted entities (like hospitals or labs) to a holder (the patient), who can then present proof to verifiers (like a new clinic) without revealing unnecessary information. This shift from institution-centric to patient-centric data models is powered by core W3C standards: Verifiable Credentials Data Model v1.1, Decentralized Identifiers (DIDs), and Linked Data Proofs.

The architecture relies on three core components. First, Decentralized Identifiers (DIDs) are the foundation, serving as persistent, cryptographically verifiable identifiers not controlled by a central registry. A patient's DID, documented in a DID Document on a ledger or other verifiable data registry, contains public keys for authentication. Second, the Verifiable Credential itself is a JSON-LD document containing claims (e.g., "vaccinationDate": "2023-10-05"), metadata about the issuer, and proof types. Third, Verifiable Presentations are how holders share credentials, often using selective disclosure to prove only that a credential is valid without revealing all its data, using techniques like BBS+ signatures.

To set up a basic issuance flow, you'll need a DID method. Let's use did:key for simplicity. First, generate a DID and its signing key pair for the issuer (e.g., a healthcare provider). Using the jsonld-signatures library, you can create a credential skeleton.

javascriptCopy
const vc = {
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://schema.org"
  ],
  "id": "urn:uuid:...",
  "type": ["VerifiableCredential", "ImmunizationRecord"],
  "issuer": "did:key:z6Mk...",
  "issuanceDate": "2023-10-05T19:73:24Z",
  "credentialSubject": {
    "id": "patient-did:key:z7Mk...",
    "vaccineType": "COVID-19 mRNA",
    "lotNumber": "12345"
  }
};

This unsigned credential is then cryptographically signed, embedding a Linked Data Proof to create the final Verifiable Credential.

For production health systems, consider privacy-enhancing features and governance. Zero-Knowledge Proofs (ZKPs) allow patients to prove they have a valid credential from a trusted issuer without revealing the credential's contents—crucial for sensitive health data. Schema.org definitions provide interoperability for health data types. Governance involves defining trust frameworks: which DIDs are authorized issuers, what credential schemas are accepted, and how keys are revoked. Projects like the Vaccination Credential Initiative (VCI) and EU Digital COVID Certificate provide real-world schemas and trust registries to study.

When implementing the verification flow, a verifier's system must: 1) resolve the issuer's DID to fetch their current public key, 2) cryptographically verify the credential's proof, 3) check the credential's status against a revocation registry (like a verifiable credential status list), and 4) validate the credential's schema and expiration. This entire process can be performed offline once the verifier trusts the issuer's DID. User-held wallets, like mobile apps implementing the W3C Verifiable Credentials API, manage the private keys and consent for sharing, completing the patient-in-control model.

The transition to verifiable health records reduces administrative overhead, minimizes data breach risks by eliminating centralized honeypots, and empowers patients. Key next steps for developers are exploring HIPAA-compliant custody solutions, integrating with FHIR (Fast Healthcare Interoperability Resources) standards for clinical data, and testing with networks like the ION DID network or Cheqd for economic sustainability. Start by experimenting with SDKs from Spruce ID's didkit, Microsoft's Verifiable Credentials SDK, or Transmute's credentials library to build prototypes.

A verifiable credentials (VC) system for health records requires a specific technical stack and architectural pattern. The core prerequisites include a decentralized identifier (DID) method for patients and providers, a verifiable data registry (like a blockchain) to anchor DIDs and credential schemas, and a credential wallet for patients. You'll need development environments for smart contracts (e.g., Solidity for Ethereum, Rust for Solana) and backend services (Node.js/Python). Familiarity with the W3C Verifiable Credentials Data Model and cryptographic primitives like digital signatures (EdDSA, ES256K) is essential.

The system architecture typically follows an issuer-holder-verifier model. Healthcare providers act as issuers, signing VCs (like vaccination records) with their private keys and publishing their public DID to a blockchain. Patients are the holders, storing these signed VCs in their secure digital wallet (e.g., a mobile app). Third parties, like a pharmacy, are verifiers who request proof, check the issuer's DID on-chain, and cryptographically validate the signature without contacting the original issuer. This architecture ensures data minimization and patient consent.

For the underlying infrastructure, you must choose a DID method and compatible blockchain. did:ethr (Ethereum) and did:sol (Solana) are common choices, where the blockchain acts as the verifiable data registry. You'll deploy a DID Registry smart contract to manage DID documents and a Credential Schema Registry to define the structure of health credentials (e.g., ImmunizationCredential). A backend issuer service is needed to create and sign VCs, while a verifier service handles presentation requests. Patient wallets interact with these services via standard protocols like OpenID for Verifiable Credentials (OID4VC).

Key design decisions impact scalability and compliance. Will you use JSON-LD with linked data proofs or JWT-based credentials? JWT VCs are simpler but JSON-LD enables more complex data graphs. You must define credential status mechanisms—using a smart contract for revocation registries is more decentralized than a centralized list. Data storage is critical: the VC itself contains only metadata and proofs; the actual health data (like PDF reports) should be stored off-chain (e.g., on IPFS or a secure server) with a hash included in the credential, ensuring patient control over data access.

To begin development, set up a local testnet (Hardhat for Ethereum, Solana Localnet) and use SDKs like Veramo (TypeScript) or Aries Framework JavaScript. Start by writing a smart contract to register DIDs, then build an issuer API endpoint that creates a signed VC. A basic credential might be a JWT containing claims like "vaccineType": "mRNA-1273" and "date": "2023-10-05", signed by a hospital's DID. The final architecture creates an interoperable, privacy-preserving system where patients own their records and can share verifiable proofs instantly.

A Verifiable Credential (VC) schema is a formal specification that defines the structure of the claims being attested. For health records, this is not a database schema but a JSON-LD or JSON Schema that standardizes data fields like patientId, diagnosisCode, medication, and issuanceDate. Using a shared schema ensures that different healthcare providers, insurers, and patients can interpret the data consistently. The W3C Verifiable Credentials Data Model is the core standard, but you must extend it for your specific use case.

Key design principles for a health data schema include minimal disclosure and selective disclosure. Instead of a monolithic record, design modular schemas for specific data types: a LabResultCredential, a VaccinationCredential, and a PrescriptionCredential. This allows a patient to share only a proof of a specific vaccination without revealing their entire medical history. Each schema should define required properties (like credentialSubject.id), optional properties, and the data type (string, number, datetime) for each field to prevent ambiguity.

Here is a simplified example of a JSON Schema for a BloodTestCredential. This defines the expected structure that a credential's credentialSubject data must adhere to, enabling validation.

jsonCopy
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "BloodTestResult",
  "type": "object",
  "properties": {
    "patientId": { "type": "string" },
    "testType": { "type": "string" },
    "resultValue": { "type": "number" },
    "unit": { "type": "string" },
    "referenceRange": { "type": "string" },
    "collectionDate": { "type": "string", "format": "date-time" },
    "performingLab": { "type": "string" }
  },
  "required": ["patientId", "testType", "resultValue", "collectionDate"]
}

After defining the schema, you must publish it to a trusted and persistent location, such as a decentralized storage network (IPFS, Arweave) or a schema registry. The schema's URI (e.g., ipfs://QmSchemaHash) is then embedded in every issued credential via the credentialSchema.id property. This allows any verifier to fetch the schema and validate the credential's structure. For production systems, consider using a schema registry like those offered by cheqd or Ethereum Attestation Service to manage versioning and revocation of schemas.

Finally, integrate privacy-enhancing technologies into your schema design. Use zero-knowledge proofs (ZKPs) to allow claims about data (e.g., "age > 18") without revealing the underlying data. Pair your schemas with BBS+ signatures (a core part of the W3C standard) to enable selective disclosure. This technical foundation ensures your system is not just interoperable but also respects patient privacy by design, moving beyond simple data portability to cryptographically-enforced data minimization.

The issuer service is a secure backend application, typically built with Node.js or Python, that acts as the trusted authority for patient health data. Its primary functions are to authenticate healthcare providers, receive structured health data payloads (like lab results or vaccination records), and package this data into a cryptographically signed Verifiable Credential. This service must integrate with existing hospital systems via APIs to fetch patient data and manage the Decentralized Identifiers (DIDs) and private keys used for signing. Security is paramount; the service's signing keys must be stored in a Hardware Security Module (HSM) or a cloud key management service like AWS KMS or Azure Key Vault to prevent unauthorized issuance.

The credential issuance process follows a defined flow. First, a healthcare professional authenticates with the system. When they request to issue a credential for a patient, the service constructs a Verifiable Credential Data Model JSON object. This includes the patient's DID as the credentialSubject.id, the health data in the credentialSubject property, metadata like issuer DID and credential type (e.g., "type": ["VerifiableCredential", "ImmunizationCredential"]), and an expiration date. The service then creates a Verifiable Presentation wrapper if needed, and finally signs the credential using JSON Web Signatures (JWS) or Linked Data Proofs with the issuer's private key, resulting in a proof section appended to the credential.

Here is a simplified Node.js code snippet using the did-jwt-vc library to create a signed JWT-based Verifiable Credential for a COVID-19 vaccination record:

javascriptCopy
const { createVerifiableCredentialJwt } = require('did-jwt-vc');
const { ES256KSigner } = require('did-jwt');

// Issuer's DID and private key (in practice, from secure storage)
const issuer = 'did:ethr:0x1234...';
const signer = ES256KSigner('0xprivateKeyHex');

const vcPayload = {
  sub: 'did:ethr:0xpatient456...', // Patient's DID
  nbf: Math.floor(Date.now() / 1000),
  vc: {
    '@context': ['https://www.w3.org/2018/credentials/v1'],
    type: ['VerifiableCredential', 'ImmunizationCredential'],
    credentialSubject: {
      id: 'did:ethr:0xpatient456...',
      vaccineCode: '207', // SNOMED CT code for COVID-19 vaccine
      lotNumber: 'AB1234',
      dateOfVaccination: '2023-10-26',
      administeringCentre: 'General Hospital'
    }
  }
};

const vcJwt = await createVerifiableCredentialJwt(vcPayload, signer, { issuer });
console.log('Issued VC JWT:', vcJwt);

After generating the signed credential, the issuer service must make it available to the patient's wallet or holder agent. This is typically done by returning the VC JWT directly through a secure API endpoint that the patient's mobile app calls, or by publishing it to a credential repository (like an encrypted cloud store) accessible via a secure link. The service should also maintain an internal, auditable ledger of all issued credentials for compliance and revocation purposes. Implementing credential status checks, such as using a Revocation List 2020, is a critical next step to allow the issuer to invalidate credentials if data is corrected or compromised.

Key architectural considerations include scalability to handle high issuance volumes, compliance with healthcare regulations like HIPAA (requiring stringent data encryption and access controls), and interoperability. The service should support multiple VC formats (JWT, JSON-LD) and proof suites to ensure the credentials can be verified by a wide array of verifier systems. By building a robust, secure issuer service, healthcare institutions establish the trusted root from which patient-controlled health data flows, enabling a new paradigm of portable and privacy-preserving health records.

A holder wallet is a patient-controlled application that stores Verifiable Credentials (VCs) issued by healthcare providers. Unlike traditional databases, this wallet gives the patient sole cryptographic control over their data. The core functions are to securely receive credentials, store private keys, and generate Verifiable Presentations (VPs) for sharing proof of specific claims without revealing the entire credential. Implementation typically uses the W3C Verifiable Credentials Data Model and standards like Decentralized Identifiers (DIDs) for interoperability.

The wallet's architecture centers on a secure key management system. For a web-based wallet, libraries like @digitalbazaar/ed25519-verification-key-2020 and @digitalbazaar/crypto-ld can generate and manage key pairs linked to the patient's DID. The private key must never leave the user's device; consider using the Web Crypto API or secure enclaves. The public key is used to create a DID Document, which is published to a Verifiable Data Registry (VDR) like a blockchain (e.g., Ethereum, Sovrin) or a DID web endpoint.

To receive a credential, the wallet must expose a standard interface. A common pattern is to provide a DIDComm messaging endpoint or a simple HTTPS API where issuers can post credential offers. Upon receiving a signed VC in JWT or JSON-LD format, the wallet must verify the issuer's signature using their public DID from the VDR before storing the credential locally in an encrypted database (e.g., IndexedDB with AES-GCM encryption).

The most critical feature is creating a Verifiable Presentation. When a verifier (like a pharmacy) requests proof of a vaccination, the wallet creates a VP. This involves selecting the relevant VC, signing a new payload containing only the required claims with the holder's private key, and optionally adding a challenge and domain from the verifier to prevent replay attacks. The output is a compact JWT or JSON-LD proof that the verifier can validate independently.

For developers, using SDKs like Veramo or Trinsic accelerates implementation. For example, with Veramo, you can create an agent, manage DIDs, and handle credentials with a few lines of code. Always prioritize user experience for key backup (seed phrases) and consent flows, ensuring the patient understands exactly what data they are sharing in each transaction.

Selective disclosure is the cornerstone of privacy in a verifiable credentials (VC) system. It allows a credential holder—in this case, a patient—to prove a specific claim derived from their credential without exposing the credential's entire contents. For health records, this means a patient can prove they are over 18 for a clinical trial, or that their vaccination status is current for travel, without revealing their full medical history, birth date, or other sensitive data. This is achieved through cryptographic zero-knowledge proofs (ZKPs), which allow one party to prove knowledge of a secret or the validity of a statement without revealing the secret itself.

The most common standard for implementing selective disclosure with JSON-based VCs is BBS+ signatures (Boneh-Boyen-Shacham with additional features). Unlike a simple digital signature that seals the entire document, a BBS+ signature allows the derivation of a proof for a subset of the signed claims. In our patient record VC, each attribute (e.g., "dateOfBirth": "1985-07-03", "bloodType": "O+") is individually signable and disclosable. The patient's wallet uses the original signed credential to generate a new, derived verifiable presentation containing only the disclosed attributes and a ZKP that cryptographically links them back to the issuer's original signature.

Here is a conceptual code example using the @mattrglobal/jsonld-signatures-bbs library to create a selective disclosure proof. First, the issuer signs the full credential with a BBS+ signature. Later, the holder creates a derived presentation.

javascriptCopy
// Holder creates a derived presentation for specific fields
const { deriveProof } = require('@mattrglobal/jsonld-signatures-bbs');

const derivedProof = await deriveProof(
  signedCredential, // The original BBS+-signed VC
  {
    "@context": signedCredential["@context"],
    "type": "VerifiablePresentation",
    "verifiableCredential": [signedCredential]
  },
  {
    suite: new BbsBlsSignature2020(),
    disclosureFrame: {
      '@context': signedCredential['@context'],
      // Only disclose these specific fields
      bloodType: true,
      // The 'dateOfBirth' field is omitted, keeping it hidden
    },
  }
);

The resulting derivedProof contains only the bloodType and a proof validating it, while dateOfBirth remains private.

For verifiers, such as a pharmacy or an insurance portal, the verification process changes slightly. Instead of checking the signature on a full credential, they verify the derived proof. They must specify the exact verification policy, which is the set of claims they require and the conditions they must satisfy (e.g., "bloodType must equal 'O+'"). The verification library cryptographically confirms that the disclosed claims are part of a valid credential signed by a trusted issuer (e.g., "General Hospital") and that the undisclosed claims have not been tampered with. This process gives the verifier the assurance they need without accessing extra data.

Designing the disclosure interface in the patient's wallet or agent is critical for usability. Patients should be presented with clear, human-readable descriptions of what data is being requested (e.g., "Share your vaccination date and type") and be able to toggle individual data points on or off. The system should also support predicate proofs, where a patient can prove a statement about a hidden attribute, such as "I am over 21 years old" without revealing their exact dateOfBirth. This is done by proving the hidden attribute satisfies a mathematical inequality within the ZKP.

Implementing selective disclosure transforms a static data dump into a dynamic, privacy-preserving tool. It aligns with regulations like GDPR's data minimization principle and empowers patients. The technical stack typically involves a BBS+-compatible signature suite for issuing, a ZKP-capable wallet for holding and deriving proofs, and verifier libraries that can process derived presentations. Frameworks like Hyperledger Aries provide agent implementations that handle these complex cryptographic operations, allowing developers to focus on defining credential schemas and user flows for specific healthcare interactions.

The verifier service is the authoritative component that receives a Verifiable Credential (VC) from a holder (e.g., a patient's wallet) and validates it against the rules of your application. Its primary functions are to verify the cryptographic proof attached to the credential and check the credential's status against a revocation registry. This ensures the data is authentic, unaltered, and currently valid before your system acts upon it, such as granting access to a medical portal or processing an insurance claim.

To build the service, you'll need to integrate a verification library. For W3C-compliant VCs with JSON-LD proofs, consider using jsonld-signatures or vc-js. For JWT-based VCs, libraries like jose are suitable. The core verification steps are: 1) Proof Verification: Validate the digital signature using the issuer's public key (often fetched from their DID Document). 2) Status Check: Query the issuer's revocation registry (e.g., a smart contract on Ethereum or a hosted service) to confirm the credential has not been revoked.

A practical implementation involves creating a REST API endpoint, such as POST /api/verify-credential. The endpoint would accept a VC in its signed format. Below is a simplified Node.js example using a hypothetical SDK:

javascriptCopy
app.post('/api/verify-credential', async (req, res) => {
  const verifiableCredential = req.body.credential;
  const issuerDid = extractIssuerDid(verifiableCredential);
  
  // 1. Resolve the Issuer's DID Document to get public key
  const issuerDoc = await didResolver.resolve(issuerDid);
  const verificationKey = issuerDoc.publicKey[0];
  
  // 2. Verify the cryptographic proof
  const proofResult = await vcVerifier.verifyProof(verifiableCredential, verificationKey);
  
  // 3. Check revocation status (e.g., via a smart contract)
  const credentialId = verifiableCredential.id;
  const isRevoked = await revocationRegistry.checkStatus(credentialId);
  
  const isValid = proofResult.verified && !isRevoked;
  res.json({ verified: isValid, proofResult, revoked: isRevoked });
});

For production systems, you must also implement credential schema validation. This ensures the VC's data structure and contents conform to an expected format, like the PatientHealthRecordSchema. Use JSON Schema validators to check that required fields (e.g., bloodType, allergies) are present and correctly typed. Additionally, verify the issuer's identity by checking if their DID is on a trusted registry or has a specific accreditation. This prevents accepting credentials from unauthorized or fraudulent healthcare providers.

Finally, design the verifier to be stateless and scalable. It should not store VCs after verification. Log verification results (without sensitive health data) for audit trails. Consider using caching for issuer DID Documents and revocation list states to improve performance. The service's output is a simple boolean (verified: true/false) and, if valid, your application logic can proceed to grant the appropriate access or service based on the claims inside the now-trusted credential.

Implementing a Verifiable Credentials (VC) system for healthcare introduces unique privacy challenges governed by regulations like HIPAA and GDPR. The core principle is data minimization: VCs allow patients to share specific, attested claims (e.g., "over 18" or "vaccination status") without exposing their full medical history. This is achieved through selective disclosure, where a verifier receives only the cryptographically proven data they need. The system's architecture must ensure the Holder (patient) maintains control over their credentials, deciding when and with whom to share them, while the Issuer (healthcare provider) and Verifier (pharmacy, insurer) never directly communicate.

Security is paramount at every layer. Credential issuance relies on Decentralized Identifiers (DIDs) and digital signatures. A healthcare provider, acting as an Issuer, signs a VC with their private key, binding the credential data to the patient's DID. This creates a tamper-evident record; any alteration invalidates the cryptographic proof. Holders store VCs in a digital wallet, which must be secured with strong authentication (biometrics, hardware keys). The verification process then uses the Issuer's public DID (resolvable from a verifiable data registry like a blockchain) to check the signature's validity without querying the Issuer's database.

For handling sensitive health data, consider zero-knowledge proofs (ZKPs). Advanced VC systems can use ZKPs to allow a patient to prove a claim derived from their health record without revealing the underlying data. For example, a patient could generate a proof that they have a valid prescription from a licensed doctor, without disclosing the doctor's name, the medication, or the diagnosis. Libraries like Hyperledger AnonCreds provide a standardized method for creating these privacy-preserving, anonymous credentials. This moves beyond simple selective disclosure to predicate proofs (e.g., "patient is over 21").

System design must enforce strict access control and audit trails. Every interaction—issuance, presentation, verification—should generate an immutable, permissioned log. While VCs themselves may be stored off-chain, the DIDs, public keys, and credential schemas are often anchored on a permissioned blockchain or other decentralized network to ensure availability and prevent revocation registry manipulation. It's critical to implement a secure credential revocation mechanism, such as a revocation registry, to instantly invalidate VCs if a private key is compromised or a credential is issued in error.

Finally, developers must plan for key management and recovery. Losing access to a wallet's private keys means losing control over all credentials. Implement social recovery or custodial options using multi-party computation (MPC) to avoid irreversible data loss. Always conduct third-party security audits on smart contracts, ZK circuits, and wallet software. Adhere to frameworks like the W3C Verifiable Credentials Data Model and DID Core specifications to ensure interoperability and compliance. The goal is a system where security is by design, enabling patient autonomy without sacrificing data integrity or regulatory compliance.

Building a production-ready system requires moving beyond the proof-of-concept. Key operational decisions include selecting a decentralized identifier (DID) method suitable for your governance model, such as did:ethr for Ethereum-based ecosystems or did:web for managed services. You must also establish a trust registry—a smart contract or a verifiable data registry—to maintain the authorized status of issuers (e.g., accredited hospitals). Crucially, design your credential schemas with long-term data interoperability in mind, aligning with standards like HL7 FHIR where possible to ensure your VerifiableCredential payloads can be understood across healthcare systems.

Security and privacy are paramount. Implement selective disclosure using technologies like BBS+ signatures to allow patients to reveal only specific claims (e.g., a vaccination date without revealing their full birth date). For sensitive data, store only credential hashes and zk-proofs on-chain, keeping the actual JSON credential off-chain, referenced via a URI. Regularly audit your smart contracts, key management procedures, and the credential revocation mechanism, whether it's a smart contract-based revocation registry or the StatusList2021 standard. Testing with tools like the W3C VC Test Suite is essential for compliance.

To extend your system, consider integrating with cross-chain attestation protocols like Ethereum Attestation Service (EAS) or Verax to record credentials on multiple networks for resilience. Explore confidential computing frameworks such as zk-proofs for complex predicate checks (e.g., "prove you are over 18 without revealing your age"). The next step is to build end-user applications: a holder wallet (a mobile app for patients to store and present credentials) and a verifier portal for healthcare providers with a simple QR code scanning interface. Start with a pilot program for a specific use case, like managing vaccination records or medical trial consent.

The ecosystem is rapidly evolving. Stay engaged with the W3C Verifiable Credentials working group and specifications like Decentralized Identifiers (DID) Core. Follow implementations from projects like Spruce ID, Dock, and Cheqd for practical insights. By implementing a verifiable credentials system, you are not just building a technical solution but contributing to a patient-centric, interoperable, and privacy-preserving future for global health data.