How to Implement Verifiable Credentials for Vendor Onboarding

Verifiable Credentials are a W3C standard for creating tamper-evident digital claims that can be cryptographically verified. In a vendor onboarding context, they allow a company (the issuer) to issue credentials—like a "KYC Verified" or "Tax Compliance Certificate"—directly to a vendor (the holder). The vendor can then present these credentials to any other party (a verifier) to prove their status without revealing unnecessary personal data. This model shifts trust from individual organizations to the cryptographic proofs and the decentralized identifiers (DIDs) of the involved parties, enabling selective disclosure and reducing redundant data collection.

Implementing VCs requires a stack of interoperable components. First, each entity needs a Decentralized Identifier (DID), a self-sovereign identifier anchored on a blockchain or other decentralized network (e.g., using the did:ethr or did:key method). The credential's data structure is defined by a JSON-LD or JWT-based schema, which includes the issuer's DID, the subject's DID, the claims, and a digital signature. The Verifiable Data Registry (often a blockchain) is used to resolve DIDs to their associated public keys and service endpoints, enabling trust in the issuer's signature. Libraries like veramo (TypeScript) or aries-framework-go provide essential tooling for creating, signing, and verifying these credentials programmatically.

A typical implementation flow involves three steps. 1. Issuance: Your company's backend, acting as issuer, creates a credential payload, signs it with the private key corresponding to its DID, and sends the signed VC (e.g., a JWT) to the vendor. 2. Storage: The vendor securely stores the VC in a digital wallet—this could be a cloud agent or a mobile app like Trinsic Studio. 3. Verification: When the vendor applies to a new partner, they generate a Verifiable Presentation, which is a wrapper for one or more VCs, often with a proof of ownership. The verifier's system checks the issuer's signature on the VC, confirms the issuer's DID is valid and not revoked on the registry, and validates the presentation's signature against the holder's DID.

For developers, here's a simplified code snippet using the veramo SDK to create a credential:

javascriptCopy
import { createAgent } from '@veramo/core';
import { CredentialPlugin } from '@veramo/credential-w3c';
// Agent setup with DID resolver and key management omitted for brevity
const credential = await agent.createVerifiableCredential({
  credential: {
    issuer: { id: 'did:ethr:0x123...' },
    credentialSubject: {
      id: 'did:ethr:0x456...',
      companyName: 'Vendor Inc.',
      complianceStatus: 'approved'
    }
  },
  proofFormat: 'jwt'
});
// `credential` is a signed JWT that can be shared and verified.

Verification uses agent.verifyCredential({ credential: jwt }) to validate the signature and status.

Key considerations for production systems include revocation mechanisms (using status lists or smart contracts), schema management for standardizing claim formats, and privacy enhancements like Zero-Knowledge Proofs (ZKPs) to prove claims (e.g., "company is over 3 years old") without revealing the underlying data. Integrating VCs into existing onboarding workflows often involves exposing a credential issuance API for approved vendors and adding a verification module to your application's intake process. This architecture significantly reduces manual review, cuts fraud risk through cryptographic verification, and gives vendors portable credentials they control.

Implementing verifiable credentials for vendor onboarding requires a shift from centralized database records to a decentralized identity model. The core prerequisites are a cryptographic identity layer and a verifiable data registry. You will need to understand the W3C standards for Decentralized Identifiers (DIDs) and Verifiable Credentials (VCs). Key libraries for implementation include did-jwt-vc for JWT-based credentials, @veramo/core for agent-based management, or credential-handler-polyfill for browser integration. A basic grasp of public-key cryptography and JSON-LD or JWT serialization is essential.

The system architecture typically involves four main actors: the Issuer (your company's compliance department), the Holder (the vendor), the Verifier (your procurement system), and the Verifiable Data Registry (a blockchain or other decentralized network). The issuer creates DIDs for itself and signs credentials. The holder stores these credentials in a digital wallet. The verifier requests and cryptographically validates proofs from the holder's wallet without contacting the issuer directly for each verification, enabling privacy-preserving checks.

For the technical stack, you must choose a DID method that defines how DIDs are created and resolved. Common choices for enterprise systems include did:ethr (Ethereum), did:web (HTTPS endpoints), or did:key (simple embedded keys). You'll also need a VC data model. The JSON-LD model with linked data proofs offers rich semantics and interoperability, while the JWT model is simpler and more compact. Your backend must run a verification agent (e.g., a Veramo agent) to perform the cryptographic operations of issuing and verifying credentials.

A critical architectural decision is selecting the verifiable data registry. While a blockchain like Ethereum or Polygon provides maximum decentralization and censorship resistance, it introduces gas costs. For many enterprise onboarding flows, a cheaper, purpose-built network like Cheqd or even a permissioned ledger may be sufficient. This registry stores the DID Documents that map a DID to public keys and service endpoints, allowing any verifier to fetch the issuer's current public key to validate a credential's signature.

Finally, the vendor (holder) experience is mediated by a wallet. This can be a mobile app (like Trinsic or Lissi), a browser extension, or a custodial wallet you provide. The wallet must support the W3C Verifiable Credentials API or the CHAPI (Credential Handler API) to receive credentials from your issuer endpoint and present proofs to your verifier. The onboarding flow involves the vendor authenticating, receiving a signed VC into their wallet, and then later granting consent to share a verifiable presentation with your procurement portal.

A Decentralized Identifier (DID) is a globally unique, cryptographically verifiable identifier controlled by its owner, independent of any centralized registry. For vendor onboarding, each vendor will have their own DID, which serves as their persistent, self-sovereign digital identity. The DID registry—often a smart contract on a blockchain—is the system of record that maps these DIDs to their associated DID Documents. This document contains the public keys, service endpoints, and other metadata necessary for verification and interaction. Choosing where to anchor this registry is your first technical decision.

You have several options for implementing the registry. You can deploy a custom smart contract using a standard like ERC-1056 (Ethereum) or ERC-5805 (Optimism), which provide interfaces for creating and updating DIDs. Alternatively, you can use a managed service like SpruceID's Credible or Microsoft's ION network, which handle the underlying infrastructure. For a vendor onboarding system requiring high throughput and low cost, a Layer 2 solution like Polygon or Arbitrum is often optimal. The key is to select a network that balances decentralization, cost, and performance for your use case.

Here is a simplified example of deploying a basic DID registry using the @veramo/did-manager and ethr-did packages for an Ethereum-compatible chain. This code initializes an agent capable of creating and managing ethr DIDs anchored to your chosen network.

javascriptCopy
import { createAgent } from '@veramo/core';
import { DIDManager } from '@veramo/did-manager';
import { EthrDIDProvider } from '@veramo/did-provider-ethr';
import { KeyManager } from '@veramo/key-manager';
import { KeyManagementSystem } from '@veramo/kms-local';

// Initialize the Veramo agent with an Ethr DID Provider
const agent = createAgent({
  plugins: [
    new KeyManager({
      store: new MemoryKeyStore(),
      kms: {
        local: new KeyManagementSystem(),
      },
    }),
    new DIDManager({
      store: new MemoryDIDStore(),
      defaultProvider: 'did:ethr:sepolia',
      providers: {
        'did:ethr:sepolia': new EthrDIDProvider({
          defaultKms: 'local',
          network: 'sepolia',
          rpcUrl: 'https://sepolia.infura.io/v3/YOUR_INFURA_KEY',
        }),
      },
    }),
  ],
});

This setup configures a DID provider for the Sepolia testnet, ready to create DIDs where the controlling private key is managed locally.

Once your registry is live, vendors can generate their own DIDs. The process involves creating a cryptographic key pair, forming a DID Document, and registering the DID's initial state on-chain. For ethr DIDs, this is often a simple transaction that writes a DIDDelegateChanged event to the Ethereum DID registry contract. The vendor's public key is the primary verification method, allowing them to sign Verifiable Credentials issued to them later. It is critical to securely manage the private keys associated with these DIDs, as they represent control over the digital identity.

The final consideration is DID resolution. Systems needing to verify credentials must be able to fetch the current DID Document for any vendor's DID. This is done via a DID resolver. You can use a universal resolver service or run your own instance that understands your chosen DID method (e.g., did:ethr:). The resolver fetches the on-chain data and constructs the current, valid DID Document, which contains the public key needed to verify a vendor's cryptographic signatures. With a functioning registry and resolver, you have established the foundational layer of trust for your credential system.

A credential schema is a foundational component in a Verifiable Credentials (VC) ecosystem. It acts as a blueprint that specifies the exact structure—the property names, data types, and formats—of the claims a credential will contain. For vendor onboarding, this could include fields like companyLegalName (string), taxId (string), yearEstablished (integer), and complianceCertifications (array). Using a shared, published schema ensures all parties—issuers, holders, and verifiers—have a common understanding of the data, enabling reliable automated processing and validation.

Designing a schema requires mapping your business requirements to a standardized format, typically JSON Schema. The schema itself is published to a persistent, immutable location, such as a decentralized storage network (IPFS) or a blockchain, resulting in a unique schema ID. This ID is then referenced within every issued credential, cryptographically linking the credential data to its structural definition. This process prevents schema drift and allows verifiers to fetch and validate the schema independently.

For implementation, you would create a JSON Schema document. Below is a simplified example for a vendor credential:

jsonCopy
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "companyLegalName": { "type": "string" },
    "jurisdiction": { "type": "string" },
    "kycStatus": { "type": "string", "enum": ["verified", "pending", "rejected"] },
    "onboardingDate": { "type": "string", "format": "date-time" }
  },
  "required": ["companyLegalName", "kycStatus", "onboardingDate"]
}

After finalizing the schema, publish it to a chosen registry. Platforms like Cheqd, Veramo, or Ethereum Attestation Service (EAS) provide tooling to anchor the schema's hash on-chain, making its ID tamper-proof and universally resolvable.

The choice of schema registry involves trade-offs between decentralization, cost, and speed. A blockchain-based registry (e.g., using the Cheqd Network or Ethereum) offers maximum immutability and censorship resistance but incurs gas fees. Alternatively, using content-addressable storage like IPFS is cost-effective and decentralized, though it may require a companion indexing service for reliable resolution. For enterprise consortia, a private, permissioned ledger might be appropriate.

Once published, the schema ID is used in the credential issuance process. When your onboarding platform issues a VC to a vendor, the credential's credentialSchema field will contain this ID. Verifiers, such as your procurement department or partner DApps, can use this ID to retrieve the exact schema and validate that the credential's data conforms to the expected structure and data types before trusting its contents. This decouples the trust in the data from the trust in the verifying application's logic.

Best practices for schema design include: versioning schemas (e.g., VendorCredential-v1.0.1) to manage updates without invalidating existing credentials, minimizing the use of required fields to maintain flexibility, and leveraging existing standard schemas from organizations like the W3C or DIF where possible to improve interoperability. Proper schema design is not a one-time task but an ongoing process that evolves with your onboarding requirements and the broader VC ecosystem.

After a vendor's identity and business details are verified in Step 2, the next step is to issue a Verifiable Credential (VC). A VC is a tamper-evident, cryptographically signed credential that contains claims about the vendor, such as their legal name, registration number, and accreditation status. Unlike a simple database entry, a VC is a portable digital asset the vendor controls. It is issued using a Decentralized Identifier (DID) as the issuer, ensuring the credential's source is cryptographically verifiable on-chain without revealing the underlying vendor data.

The credential's data model follows the W3C Verifiable Credentials Data Model standard. A typical vendor credential payload in JSON-LD format includes the credential's unique ID, the issuer's DID, the issuance date, the credential subject (the vendor's DID), and the credential claims. The claims are structured within a credentialSubject object. For example, a credential might assert "accreditedVendor": true and "kycLevel": "Enhanced". This structure ensures interoperability across different verifier systems in the Web3 ecosystem.

To issue the credential, you must sign the payload. This is typically done using the JSON Web Token (JWT) or Data Integrity proof format. For a JWT, you create a signed JWT where the payload is the VC data. The signing key must be the one associated with the issuer DID documented in its DID Document. On Ethereum-compatible chains, this often uses the ethsign signing method with the issuer's private key. Libraries like did-jwt-vc or veramo abstract this process. The output is a compact JWT string that serves as the verifiable credential.

For maximum security and user-centric control, you should issue the credential to a holder—often the vendor's own mobile wallet app that supports VCs, like an identity wallet. The issuance protocol can be a simple API call returning the JWT or a more complex interaction using OpenID for Verifiable Credentials (OIDC4VC) or Credential Handler API (CHAPI). The vendor's wallet receives and stores the credential in its secure storage, creating a Verifiable Presentation when needed for verification. This completes the vendor's onboarding, granting them a reusable, privacy-preserving proof of their verified status.

The verification portal is the user-facing interface where vendors interact with your credential system. Its primary functions are to allow vendors to submit credential claims, manage their verifiable credential (VC) wallet, and view their verification status. For verifiers (like procurement officers), it provides a dashboard to review submissions, initiate verification checks, and approve or reject applications. A well-designed portal abstracts the complexity of the underlying cryptographic proofs, making the process accessible.

Start by building the credential submission flow. Vendors should be able to upload evidence (e.g., business licenses, tax documents) and fill out structured forms. This data forms the set of claims that will later be signed into a VC. Use form validation to ensure data quality. For the backend, you'll need API endpoints to receive this data, store it temporarily in a database (like PostgreSQL), and trigger the credential issuance process. Consider using frameworks like Next.js or React with a Node.js backend for a full-stack implementation.

Next, integrate a wallet solution for vendors to store their issued VCs. You can embed a lightweight wallet like Spruce ID's Credible or use WalletConnect to connect existing mobile wallets. The portal must provide clear instructions for vendors to save their credential. A critical feature is the Presentation Request interface, where verifiers can generate a QR code or a deep link asking for specific credentials (e.g., "Proof of Business Registration"). The vendor's wallet uses this request to create a verifiable presentation, which is sent back to the portal for verification.

The verification logic is the core of the portal. When a presentation is received, your backend must verify the cryptographic signature on the VC and check the status of the credential (e.g., against a revocation registry). For W3C-compliant VCs using JSON-LD, libraries like jsonld-signatures or vc-js can handle this. For simpler JWTs, verification is straightforward with JWT libraries. Log all verification attempts and results for audit purposes. The portal should then update the vendor's application status accordingly, notifying both the vendor and the verifier.

Finally, implement role-based access control (RBAC) and audit logs. Verifiers should only see applications in their purview. All actions—submissions, verifications, approvals—should be immutably logged, potentially on-chain for high-stakes use cases. For a production system, ensure you follow data privacy regulations (like GDPR); consider storing only hashes or decentralized identifiers (DIDs) on-chain, keeping sensitive claim data off-chain with selective disclosure.

On-chain revocation status is a critical component for trustless verification. Instead of relying on a centralized issuer to answer status queries, the revocation state is stored as a public, immutable record on a blockchain like Ethereum or Polygon. This allows any verifier, such as a DeFi protocol during vendor onboarding, to autonomously check a credential's validity by reading from the chain, eliminating issuer availability as a single point of failure and enhancing system resilience.

The most common pattern is to use a revocation registry smart contract. This contract maintains a mapping, often a bitfield or a Merkle tree, linking credential identifiers (like a unique credentialId hash) to a boolean revocation status. When an issuer needs to revoke a credential, they submit a transaction to update this mapping. The associated transaction hash serves as cryptographic proof of the revocation action and its timestamp. Popular frameworks like Hyperledger AnonCreds utilize this model.

For implementation, you can deploy a simple registry contract. The following Solidity snippet shows a basic structure using a mapping. The revokeCredential function is permissioned, typically allowing only the credential issuer to call it.

solidityCopy
contract RevocationRegistry {
    address public issuer;
    mapping(bytes32 => bool) public revokedCredentials;

    constructor() {
        issuer = msg.sender;
    }

    function revokeCredential(bytes32 credentialId) external {
        require(msg.sender == issuer, "Not authorized");
        revokedCredentials[credentialId] = true;
    }

    function isRevoked(bytes32 credentialId) external view returns (bool) {
        return revokedCredentials[credentialId];
    }
}

During the verification flow, the vendor's client application must query this on-chain status. Using a library like ethers.js, the verifier calls the registry's isRevoked view function, passing the credential's unique identifier. A return value of true means the credential is invalid and the onboarding check should fail. This query is a gas-free read operation, making it cost-effective for verifiers. It's essential to design the credential schema to include the registry's contract address and the credential's specific credentialId for this lookup.

For scalability and privacy, consider advanced models like revocation using Merkle trees. In this scheme, the smart contract only stores a single Merkle root representing the current state of all non-revoked credentials. Issuers provide verifiers with a Merkle proof that a specific credential is included in that root. Revocation involves updating the root to exclude the credential. While more complex, this method batches updates and hides which specific credential was revoked in a set, offering better privacy for certain use cases.

Finally, integrate this check into your vendor onboarding logic. The sequence is: 1) Parse the Verifiable Credential presented by the vendor, 2) Extract the revocationRegistryAddress and credentialId, 3) Query the on-chain registry, 4) Proceed only if isRevoked returns false. This creates a robust, decentralized check that the vendor's accreditation, KYC proof, or insurance documentation is currently active, a fundamental requirement for automated, secure onboarding in Web3 ecosystems.

Verifiable Credentials (VCs) are a W3C standard for creating tamper-proof, cryptographically signed digital attestations. In a vendor onboarding context, a VC can represent a business license, tax ID, or insurance certificate issued by a trusted authority. Unlike traditional document sharing, VCs enable selective disclosure, allowing vendors to prove specific claims (e.g., "is licensed in California") without revealing the entire credential's data. This is powered by zero-knowledge proofs (ZKPs) or simpler signature schemes like BBS+, which separate the proof from the raw data.

The implementation stack typically involves three roles defined by the Decentralized Identifier (DID) specification: the Issuer (e.g., a government agency), the Holder (the vendor), and the Verifier (your platform). A vendor obtains a VC from an issuer and stores it in a digital wallet. When your platform requests proof, the wallet generates a Verifiable Presentation containing only the necessary, cryptographically verifiable claims. This architecture eliminates the need for your platform to store sensitive PII, shifting the data custody and compliance burden to the vendor.

To build this, start by choosing a DID method and VC data model. For Ethereum ecosystems, did:ethr or did:key are common. Use libraries like Veramo (TypeScript) or Aries Framework JavaScript to handle credential issuance and verification. The core flow involves: 1) Your platform requesting a specific claim via a Presentation Definition, 2) The vendor's wallet creating a proof, and 3) Your backend verifying the proof's signature and checking the issuer's DID against a trust registry or revocation list.

For example, to verify a vendor is over 18, you wouldn't need their birthdate. Using a ZKP-capable VC, they can prove the statement "age > 18" is true. In code with Veramo, verification involves checking the proof against the issuer's public key. Here's a simplified snippet for verifying a JWT-formatted VC:

javascriptCopy
const result = await agent.verifyCredential({
  credential: verifiableCredentialJWT,
});
if (result.verified) {
  // Check the specific claim from `result.credential.credentialSubject`
}

Key considerations for production include managing credential revocation using status lists or smart contracts, establishing a trust framework for issuer DIDs, and ensuring wallet interoperability. Standards like OpenID for Verifiable Credentials (OIDC4VC) facilitate integration with existing auth flows. This approach future-proofs onboarding by supporting credentials from any compliant issuer, reducing manual checks, and significantly enhancing vendor privacy and control over their data.

Implementing verifiable credentials (VCs) transforms vendor onboarding from a manual, trust-heavy process into an automated, cryptographic protocol. The system's security hinges on three pillars: the issuer's digital signature, the holder's control over their decentralized identifier (DID), and the verifier's ability to cryptographically check credential validity without contacting the issuer. By using standards like the W3C Verifiable Credentials Data Model, you ensure interoperability across different platforms and future-proof your application. The primary benefit is a significant reduction in fraud risk and administrative overhead, as credentials cannot be forged and their validity can be programmatically assured.

Your next step is to choose and integrate a credential issuance framework. For Ethereum-based systems, consider tools like ethr-did for DID management or Veramo for a modular agent framework. If you are building on other chains, explore Spruce ID's Kepler storage or Microsoft's ION for Bitcoin-based DIDs. A minimal issuance flow involves: 1) The vendor generates a DID and provides the public key, 2) Your onboarding service (the issuer) creates a signed VC containing the vendor's accredited status, and 3) The credential is delivered to the vendor's secure digital wallet, such as Spruce's Credible or a custom custodial solution.

For the verification side, you must embed logic into your procurement or vendor portal. This involves a service that performs the credential verification steps: parsing the VC, checking the issuer's signature against their known DID, validating the credential's status (ensuring it hasn't been revoked), and confirming the proof presentation is from the rightful holder. Libraries like verite by Circle or DIDKit by Spruce provide reusable functions for these checks. Here is a conceptual code snippet for a verification function:

javascriptCopy
async function verifyVendorCredential(presentation) {
  const result = await didKit.verifyPresentation({
    presentation: presentation,
    challenge: 'your-unique-session-challenge', // Prevents replay attacks
  });
  return result.verified && result.credentialStatus === 'valid';
}

Finally, plan for credential lifecycle management. A production system requires a revocation registry (e.g., using a smart contract as a revocation list) to handle cases where a vendor's status changes. You should also design a re-issuance process for expired credentials and establish clear governance policies defining who can issue credentials and under what criteria. Start with a pilot program for a small vendor cohort, monitor gas costs and user experience, and iterate based on feedback. The end goal is a seamless, self-sovereign identity layer that makes onboarding scalable, secure, and compliant.