How to Implement a Verifiable Credentials System for Medical Records

Verifiable Credentials (VCs) are a W3C standard for creating tamper-proof digital credentials that can be cryptographically verified. In healthcare, this enables a patient to hold their own medical records—like immunization history or lab results—in a digital wallet. The issuer (e.g., a hospital) signs the credential, the holder (patient) stores it, and any verifier (e.g., a clinic) can instantly check its authenticity without contacting the issuer. This shifts control from centralized databases to the individual, enabling patient-centric data interoperability while maintaining strict privacy and security.

The foundational layer for VCs is Decentralized Identifiers (DIDs). A DID is a unique, self-sovereign identifier controlled by the holder, not a central authority. For a medical VC system, you need three DID methods: one for the issuing institution, one for the patient, and one for the verifying entity. Implement this using a DID library like did-jwt-vc or veramo. First, create a DID document for the hospital, which contains its public key for signing. The patient's DID, often managed by a mobile wallet app, will be used to receive and present credentials.

To issue a credential, the hospital creates a JSON-LD document following the Verifiable Credentials Data Model. This includes the credential's issuer (hospital's DID), the credentialSubject (patient's DID and the medical claims), and metadata like the issuance date. The hospital then cryptographically signs this document, creating a JWT (JSON Web Token) or a Linked Data Proof. Here's a simplified code snippet for creating a signed immunization credential using the veramo SDK in TypeScript:

typescriptCopy
const verifiableCredential = await agent.createVerifiableCredential({
  credential: {
    issuer: { id: 'did:ethr:0x123...' },
    credentialSubject: {
      id: 'did:key:z6Mk...',
      immunization: {
        vaccineCode: '207',
        lotNumber: 'AB12345',
        date: '2023-10-15'
      }
    }
  },
  proofFormat: 'jwt'
});

The patient stores this signed VC in their digital identity wallet. When needing to share proof of vaccination at a new clinic, they don't send the raw credential. Instead, they create a Verifiable Presentation. This is a wrapper, often also a signed JWT, that contains the relevant credential(s) and is sent to the verifier. The presentation can use selective disclosure techniques like BBS+ signatures to reveal only specific attributes (e.g., "over 18" or "vaccinated for COVID-19") without exposing the entire record, enhancing privacy.

The verifying clinic uses the issuer's public key (resolved from the hospital's DID document on a Verifiable Data Registry like a blockchain or DID web service) to check the credential's signature. It also checks the credential status—often via a revocation registry—to ensure it hasn't been revoked. The entire verification is a local cryptographic check, eliminating the need for slow, privacy-invasive database calls. This architecture enables real-time, trustless verification of medical data across organizational boundaries.

For production, consider interoperability standards like SMART Health Cards for specific clinical data formats and HL7 FHIR for underlying health data models. Key challenges include designing a user-friendly wallet UX, managing key loss/recovery, and ensuring the system complies with regulations like HIPAA or GDPR. Successful implementations, such as the EU's EBSI (European Blockchain Services Infrastructure) for educational credentials, provide a blueprint for scalable, sovereign medical identity systems.

Before writing any code, you must define the core data schemas and issuer governance. A medical credential schema, such as a VaccinationRecord or LabResult, must be standardized using formats like W3C JSON-LD or a simpler JSON schema. This defines the structure of the credential's claims (e.g., vaccineType, dateAdministered, lotNumber). Crucially, you must establish a trust registry—a decentralized list of authorized issuers (like hospitals or clinics) whose digital signatures will be recognized by verifiers. This can be implemented using a smart contract on a blockchain like Ethereum or Polygon, or a more traditional, audited API.

The system architecture revolves around three primary actors defined by the W3C standard: the issuer (healthcare provider), the holder (patient), and the verifier (pharmacy, insurance company). The issuer signs credentials with a private key, creating a cryptographic proof. The holder stores these credentials in a digital wallet—a secure, user-controlled application. The verifier requests specific credentials from the holder and cryptographically validates the issuer's signature and the credential's integrity without contacting the issuer directly. This privacy-by-design architecture eliminates the need for centralized databases of sensitive data.

For the technical stack, you will need to choose a Decentralized Identifier (DID) method. DIDs are self-sovereign identifiers (e.g., did:ethr:0x...) that are controlled by the holder or issuer, not a central authority. Common methods include did:ethr (Ethereum), did:key, or did:web. Your implementation will require libraries to create DIDs, sign Verifiable Credentials (VCs), and create Verifiable Presentations (VPs). For Ethereum-based systems, consider the ethr-did-resolver and veramo framework. For a more general approach, the did-jwt-vc library provides tools for creating and verifying JWT-encoded credentials.

The holder's wallet is a critical component. It must securely manage private keys, store VCs, and facilitate the presentation process. For a web or mobile application, you can integrate wallet SDKs like Veramo Agent or Trinsic. The wallet generates a VP, which is a cryptographically signed package of selected credentials that satisfies a verifier's request. For example, a pharmacy may request proof of a COVID-19 vaccination without needing to see the patient's entire medical history. The wallet allows the user to consent to sharing only the specific, required data.

Finally, you must plan for revocation and status checks. Credentials like medical licenses or test results have a validity period. Implementing a revocation mechanism, such as a revocation list (e.g., a W3C Status List 2021) or a smart contract that maintains a registry of revoked credential IDs, is essential. The verifier's process must include checking this status to ensure the presented credential is still valid. This completes the core loop: Issue → Store → Present → Verify, creating a system where trust is cryptographic and user consent is paramount.

The issuer service is the authoritative backend system that creates and cryptographically signs Verifiable Credentials. For medical records, this is typically a hospital's IT system or a certified health application. Its core responsibilities are to authenticate the subject (the patient), structure their data according to a defined schema, and produce a digitally signed credential. We'll implement this using Node.js, the did:ethr method for Decentralized Identifiers (DIDs), and the @veramo/core framework, a popular toolkit for building verifiable data applications.

First, define the credential schema. This JSON structure dictates the data fields in the VC. For a vaccination record, it might include patientDID, vaccineName, dateAdministered, lotNumber, and administeringClinic. Using a shared, public schema ensures any verifier can interpret the credential's contents. Next, generate a DID for your issuing institution using an Ethereum wallet (e.g., via ethr-did). This DID, anchored on-chain, serves as your institution's permanent, cryptographically verifiable identity for signing credentials.

The signing process is critical. When a patient requests a record, your service creates a JSON object containing the credential subject's DID, the schema-defined claims, and metadata like issuance date. Using Veramo, you sign this object with the private key corresponding to your institution's DID. This generates a JWT or JSON-LD Proof, embedding the signature. The output is the complete Verifiable Credential. For example, a signed credential payload would include a proof section with type, verificationMethod (your DID), and the jws signature string.

This service must expose a secure API endpoint (e.g., POST /issue-credential) for authorized systems to request VCs. It should integrate with your existing patient authentication and Electronic Health Record (EHR) database to fetch accurate data. The endpoint accepts a patient identifier, fetches the relevant medical data, constructs the VC, signs it, and returns the final credential to the caller—which could be a patient's wallet app. All private keys must be stored in a secure, managed solution like a Hardware Security Module (HSM) or cloud KMS.

Finally, consider revocation. While VCs are designed to be self-verifiable, you may need to invalidate them (e.g., if data is corrected). Implement a simple revocation registry, such as storing revoked credential IDs in a smart contract on Ethereum or using the Status List 2021 VC extension. Your issuer service should provide a standard endpoint (e.g., GET /credentials/status/:id) for verifiers to check a credential's active status, completing the trust cycle.

The holder wallet is the patient's digital identity hub. Unlike traditional databases, it is a self-sovereign application that runs on the user's device (like a smartphone app or browser extension). Its core responsibilities are to: securely store private keys, manage Decentralized Identifiers (DIDs), receive and store Verifiable Credentials (VCs) from issuers like hospitals, and create Verifiable Presentations (VPs) to share specific data with verifiers. For medical records, this architecture ensures the patient has granular control over their sensitive health data, deciding exactly what to share and with whom.

To build a basic holder wallet, you need to implement a few key cryptographic operations. First, generate a DID and its associated keys. Using the did:key method with the Ed25519 signature suite is a common starting point for simplicity. The following JavaScript example uses the @digitalbazaar/ed25519-verification-key-2020 and @digitalbazaar/ed25519-signature-2020 libraries:

javascriptCopy
import { Ed25519VerificationKey2020 } from '@digitalbazaar/ed25519-verification-key-2020';
import { Ed25519Signature2020 } from '@digitalbazaar/ed25519-signature-2020';

const keyPair = await Ed25519VerificationKey2020.generate();
const did = `did:key:${keyPair.fingerprint()}`; // e.g., did:key:z6Mk...

This did and the private component of keyPair form the core of the holder's identity.

The wallet must provide a secure key management system. Private keys should never leave the user's device unencrypted. Use the Web Crypto API or platform-specific secure enclaves (iOS Keychain, Android Keystore) for storage. The wallet's interface should allow users to view their received VCs (e.g., "COVID-19 Vaccination Record from City Hospital"), select which credentials to include in a presentation, and specify the purpose for sharing (like "for pharmacy prescription verification"). This selective disclosure is a fundamental privacy feature of VC systems.

Finally, the wallet needs to communicate with issuers and verifiers. It exposes a standard interface, often as a DIDComm agent or by implementing the W3C Credential Handler API (CHAPI). When a verifier (like a new specialist's office) requests proof of a vaccination, your wallet receives a Presentation Request. It then uses the stored private key to cryptographically sign a Verifiable Presentation containing the relevant VC and sends it back. This entire flow happens without the wallet provider or any other intermediary ever accessing the user's raw credential data.

The verifier is the component that receives and validates a Verifiable Presentation from a patient's wallet. Its primary responsibilities are to: verify the cryptographic proof attached to the credential, confirm the credential's status (e.g., not revoked), and check that the credential's schema matches the expected format for the requested medical service. This is a stateless service that can be integrated into hospital portals, telemedicine apps, or research platforms. It uses the public keys and Decentralized Identifiers (DIDs) of trusted issuers (like medical boards or hospitals) to perform these checks without needing to contact the issuer directly for every verification.

Implementation begins by setting up a verification service using a library like did-jwt-vc for JWT-based credentials or jsonld-signatures for JSON-LD/Linked Data proofs. The core verification flow involves three steps: Proof Verification, Status Check, and Schema Validation. For proof verification, the service resolves the issuer's DID from the credential to obtain their public key, then cryptographically verifies the signature. This ensures the credential was issued by a trusted entity and has not been tampered with.

Next, the service must check the credential's revocation status. For credentials using a revocation registry (like in Hyperledger Indy or AnonCreds), the verifier queries the registry's smart contract or ledger to ensure the credential hasn't been revoked. For status list methods like W3C's Status List 2021, it fetches the status list credential and checks the relevant index bit. This step is critical for maintaining trust, as a credential can be invalidated if a patient's license is suspended or information is corrected.

Finally, the verifier validates the credential's contents against a predefined schema. This ensures the presented data (e.g., medicalLicense.type or vaccination.date) conforms to the expected structure and data types required by your application. You can reference schema IDs from a registry like the Ethereum Attestation Service (EAS) or a custom schema manager. Only after all three checks pass should the application grant access to the restricted service or data.

Here is a simplified Node.js code snippet using the did-jwt-vc library to verify a JWT Verifiable Credential:

javascriptCopy
import { verifyCredential } from 'did-jwt-vc';
import { Resolver } from 'did-resolver';
import { getResolver } from 'web-did-resolver';

const didResolver = new Resolver({ ...getResolver() });

async function verifyMedicalCredential(jwt) {
  const verificationResult = await verifyCredential(jwt, didResolver);
  
  if (!verificationResult.verified) {
    throw new Error('Credential proof invalid: ' + verificationResult.error);
  }
  
  // Check custom claims against expected schema
  const payload = verificationResult.payload;
  if (payload.vc.credentialSubject.credentialType !== 'MedicalLicense') {
    throw new Error('Credential schema mismatch');
  }
  
  // Perform status check (pseudo-code for a registry)
  const isRevoked = await checkStatusRegistry(payload.jti);
  if (isRevoked) throw new Error('Credential revoked');
  
  return { verified: true, payload: payload.vc.credentialSubject };
}

For production systems, consider caching DID documents and status lists to improve performance. The verifier should also log all verification attempts (without storing personal health information) for audit trails. By implementing these checks, you create a trust-minimized gateway that relies on cryptographic proofs and decentralized status checks, eliminating the need for direct API calls to issuers and enabling seamless, privacy-preserving verification of medical credentials across organizational boundaries.

A Verifiable Credentials (VC) system for medical records shifts the paradigm from centralized data silos to patient-controlled, portable digital proofs. Built on the W3C standard, it allows a hospital to issue a cryptographically signed credential (like a vaccination record) to a patient's Decentralized Identifier (DID). The patient can then present this credential to a pharmacy or insurance provider, who can instantly verify its authenticity without contacting the original issuer. This architecture minimizes data exposure and puts the patient in control of their information flow, addressing core HIPAA and GDPR compliance challenges by design.

The security model relies on public key cryptography and digital signatures. When issuing a credential, the hospital signs the data (e.g., { "vaccine": "COVID-19", "date": "2023-10-01", "lot": "AB1234" }) with its private key, binding it to the patient's DID. The resulting VC is stored in the patient's digital wallet (e.g., a mobile app). To present it, the patient creates a Verifiable Presentation, which may include only a subset of the data (selective disclosure) and is signed with their own private key. Verifiers check both signatures against the public keys published on the issuers' and holders' DID documents, typically resolved via a blockchain or distributed ledger.

For medical data, selective disclosure and zero-knowledge proofs (ZKPs) are critical for privacy. Instead of showing an entire health record, a patient can prove they are over 18 or had a specific test result without revealing their birthdate or the result value. Using BBS+ signatures or zk-SNARKs, the credential can be cryptographically transformed to prove predicates about the data. For example, a credential could generate a proof for the statement "vaccination date > 2023-01-01" that is verifiable but reveals nothing else. This minimizes the attack surface and data leakage.

Implementation requires choosing a DID method (e.g., did:ethr for Ethereum, did:key for simplicity), a signature suite (e.g., Ed25519Signature2018, BbsBlsSignature2020 for ZKPs), and a credential format (JSON-LD or JWT). Developers can use libraries like Veramo (TypeScript) or Aries Framework JavaScript. A basic issuance flow involves creating a DID for the patient, building a credential payload, signing it, and transmitting it via a secure channel like DIDComm. The wallet must securely manage private keys, often using hardware security modules or secure enclaves.

Key architectural decisions impact security. Credential revocation can be handled via status lists (published JSON files), smart contract registries, or accumulator-based methods like revocation bitmaps. Credential binding ensures the VC is only usable by the rightful holder, typically achieved by requiring the holder to sign a challenge during presentation. Audit logging of issuance and presentation events—while preserving privacy—is essential for compliance. All interactions should use secure, authenticated protocols like OIDC4VP or DIDComm v2 to prevent man-in-the-middle attacks.

Deploying this system requires careful key management for issuers, secure wallet design for holders, and reliable resolver infrastructure for verifiers. Start with a pilot for low-sensitivity data, using testnets like Ethereum Sepolia for DID registration. The ultimate goal is interoperability: systems built on open standards allow credentials from one hospital to be verified by any clinic globally, creating a patient-centric health data ecosystem that is both private and verifiable.

You have now built the foundational elements: issuing W3C-compliant Verifiable Credentials (VCs) with a Decentralized Identifier (DID), creating a secure holder wallet, and enabling verifiable presentations. The critical next phase is system integration. This involves connecting your issuer backend (e.g., a hospital's EHR system) to the credential issuance service, embedding the verification logic into patient portals or third-party apps, and establishing a robust key management strategy for your organization's DID. Consider using frameworks like Spruce ID's Credible or Microsoft's ION for scalable DID operations.

For production deployment, prioritize privacy and compliance. Implement Selective Disclosure (using BBS+ signatures) to allow patients to share only specific data points, like a vaccination status without revealing their full birth date. Ensure your system adheres to regulations like HIPAA and GDPR by designing data minimization into the VC schema itself. Audit trails for credential issuance and verification should be maintained off-chain, with only the cryptographic proofs living on the ledger. Tools like Hyperledger Aries provide protocols for secure, private credential exchanges.

Finally, plan for ecosystem growth. Start by onboarding trusted partners, such as pharmacies or insurance providers, as verifiers in your network. Develop clear governance models for schema evolution and DID key rotation. Monitor the performance of your chosen blockchain (e.g., transaction costs on Ethereum L2s like Polygon or speed of Sidetree-based networks like ION). The ultimate goal is a system where patient agency, data integrity, and clinical utility converge, moving beyond legacy data silos to a new standard of interoperable and user-centric health data.