LearnVC

Build a verifier

You run the buyer or retailer side. As a coordinator you speak VCALM — just the coordinator side of it. You don't run VCALM delivery, the on-the-wire exchange with the product's wallet; a workflow service does that and verifies the credential for you. Your job is three calls: create an exchange, share an interaction URL that points the product's wallet at it, then poll until the verified result comes back.

What the coordinator does

  1. Create an exchange against a workflow that requests the authenticity credential and names the brands you trust.
  2. Host and share an interaction URL that points the product's wallet at that exchange.
  3. Poll the exchange until it completes, then read the verified result.

The workflow service does the rest — it sends the presentation request, receives the wallet's response, and verifies the proof, challenge, domain, trusted issuer, and status before it ever returns a result to you.

1. Create the exchange

POST to your workflow's exchanges endpoint. The workflow already encodes request a product passport and trust the real brand; you pass just the per-exchange variables: 

POST https://workflows.example/workflows/authenticity-check/exchanges
{
  "ttl": 900,
  "variables": {
    "reason": "Please present this product's authenticity credential."
  }
}

This call is authenticated. On success the service returns 204 No Content with a Location header — your exchange URL: 

HTTP/1.1 204 No Content
Location: https://workflows.example/workflows/authenticity-check/exchanges/z19xQ...

The workflow's challenge and domain stop a captured presentation from being replayed; its trustedIssuer setting requires the credential come from the real brand.

2. Host and share the interaction URL

The exchange URL is the vcapi interaction endpoint. Hosting and sharing it is the coordinator's responsibility — put it on a tag, QR code, or link, typically wrapped in a presentation request: 

{
  "VerifiablePresentation": {
    "interact": {
      "service": [{
        "type": "VerifiableCredentialApiExchangeService",
        "serviceEndpoint": "https://workflows.example/workflows/authenticity-check/exchanges/z19xQ..."
      }]
    }
  }
}

The product's wallet POSTs to that endpoint and runs the exchange with the workflow service directly. You are not in that loop.

3. Poll for the verified result

GET the exchange URL (authenticated) until its state is complete: 

GET https://workflows.example/workflows/authenticity-check/exchanges/z19xQ...
{
  "exchange": {
    "id": "z19xQ...",
    "state": "complete",
    "variables": {
      "results": {
        "authenticityCheck": {
          "did": "did:example:bag-456",
          "verifiablePresentation": { "...": "verified: the authenticity VC" }
        }
      }
    }
  }
}

A complete state means the workflow service already verified the presentation for you — proof, challenge, domain, trusted issuer, and revocation/expiry status. The verified result lands under exchange.variables.results, keyed by the workflow's step names.

That's it

A provenance verifier, as a coordinator, is these three calls: create an exchange, host and share the interaction URL, poll for the verified result. The cryptographic verification and protocol interop are the workflow service's job — you create exchanges and read what comes back.

On the wallet end, a standalone client-side VCALM library is still planned; until it ships, wallets run the exchange over the raw HTTP flow. The coordinator side shown here works today against any VCALM workflow service, such as one running @bedrock/vc-delivery.

Go deeper

← Back to roles