DPP

Build a signed Verifiable Credential (self-hosted certificate)

Builds and signs the exact W3C Verifiable Credential the platform would otherwise upload to IPFS for the given passport content — without persisting or anchoring anything. The issuer hosts the returned credential at their own https URL and passes it back as certificateUri on create/update, enabling a deletable (self-hosted) certificate. Send the SAME product/data/certifiedPaths you will send to create, so the on-chain content hash matches the hosted credential. Signed with the active certification key of the organization.

post/v1/dpp/passports/build-vc

Request

  • Base URL: https://api.prod.keyban.io
  • URL: https://api.prod.keyban.io/v1/dpp/passports/build-vc
  • Auth: API key in header X-Api-Key

Request body

network'EthereumAnvil' | 'BaseSepolia' | 'BaseMainnet' | 'XdcApothem' | 'XdcMainnet' | 'StellarQuickstart' | 'StellarTestnet' | 'StellarMainnet' required

Blockchain network on which the passport is anchored. Passports are anchored on EVM networks (e.g. BaseMainnet).

status'draft' | 'published' | 'claimed' | 'archived'

Lifecycle status. draft is editable and not certified; published triggers on-chain certification; claimed is set on item passports once they have been minted to an end-user account; archived is read-only. The transition draft → published is one-way: a published passport cannot be reverted to draft.

webPageUrlstring nullable

Absolute URL of the product's own web page on the brand or merchant site — the page a shopper lands on (RFC 3986). Not a link to an image, a document or the passport itself.

dataobject

Free-form business payload (attributes, traceability, compliance fields, ...). Consumed as the source object for the certified snapshot — see certifiedPaths.

certificateUristring nullable

Optional https URL to a self-hosted signed Verifiable Credential. When provided on create/update, the server anchors this URI on-chain instead of uploading the credential to IPFS — letting the issuer host (and delete) the certificate itself for data-protection compliance. The hosted credential must be the exact VC returned by POST /v1/dpp/passports/build-vc for the same content. Must be sent together with certificateSignature. Leave null/absent to use the default IPFS flow.

certificateSignaturestring nullable

The self-hosted credential's Data Integrity proof value (the VC proof.proofValue, multibase base58btc). Required together with certificateUri: it is anchored on-chain so a verifier can pin the served credential to its on-chain record (a self-hosted URL is mutable and not content-addressed). Anchoring it without re-supplying it when the certified content changes is rejected. Ignored for the IPFS flow.

certifiedPathsstring[]

Dot-notation paths selecting which fields from data are included in the signed certificate. When empty, the entire data object is certified. Example: ["brand", "gtin", "manufacturer.name"]. Updating this array on a published passport triggers a re-certification.

allowedClaimEmailstring email nullable

Email address authorized to claim this item. Empty string is coerced to null (no restriction).

allowedClaimPhoneNumberstring e164 nullable

E.164 phone number authorized to claim this item. Empty string is coerced to null (no restriction).

applicationstring uuid required
contentHashstring

Client-computed hash of the PLAINTEXT certified content, anchored on-chain in the certification event instead of the server-computed hash — lets holders of a clear certificate verify passports whose data is encrypted client-side. SHA-256 over the JCS (RFC 8785) canonical {type: 'Data', data}, full digest: 0x + 64 lowercase hex. Format-validated only, never returned by the API, and cleared when data/certifiedPaths/product are updated without resending it (fallback to the server-computed hash).

Example request

{
  "network": "BaseMainnet",
  "status": "published",
  "webPageUrl": "https://brand.example.com/products/hiking-boots",
  "product": {
    "name": "Trail Runner Hiking Boots",
    "description": "Waterproof hiking boots with reinforced ankle support, built for multi-day treks.",
    "modelNumber": "TRB-2400",
    "batchNumber": "LOT-2026-03-A",
    "itemNumber": "SN-000482913",
    "productImage": {
      "linkURL": "https://brand.example.com/products/hiking-boots/front.jpg",
      "linkName": "Front view",
      "digestMultibase": "zQmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
      "mediaType": "image/jpeg",
      "linkType": "productImage"
    },
    "productCategory": [
      {
        "code": "6402.91",
        "name": "Waterproof footwear covering the ankle",
        "schemeID": "https://vocabulary.uncefact.org/CPC",
        "schemeName": "CPC"
      }
    ],
    "relatedDocument": [
      {
        "linkURL": "https://brand.example.com/docs/care-instructions.pdf",
        "linkName": "Care instructions",
        "mediaType": "application/pdf"
      }
    ],
    "relatedParty": [
      {
        "role": "manufacturer",
        "party": {
          "id": "https://id.gs1.org/414/1234567890128",
          "name": "Acme Corp"
        }
      }
    ],
    "producedAtFacility": {
      "id": "https://id.gs1.org/414/1234567890128",
      "name": "Acme Corp — Lyon Plant",
      "registeredId": "3760123450016"
    },
    "countryOfProduction": {
      "countryCode": "FR",
      "countryName": "France"
    },
    "dimensions": {
      "weight": {
        "value": 1.2,
        "unit": "GRM"
      },
      "length": {
        "value": 1.2,
        "unit": "MTR"
      },
      "width": {
        "value": 1.2,
        "unit": "MTR"
      },
      "height": {
        "value": 1.2,
        "unit": "MTR"
      },
      "volume": {
        "value": 1.2,
        "unit": "STL"
      }
    },
    "materialProvenance": [
      {
        "name": "Full-grain leather",
        "originCountry": {
          "countryCode": "IT"
        },
        "materialType": {
          "code": "291000",
          "name": "Leather",
          "schemeID": "https://vocabulary.uncefact.org/CPC",
          "schemeName": "CPC"
        },
        "massFraction": 0.6
      }
    ],
    "packaging": {
      "description": "Recycled cardboard box with a paper honeycomb inner liner.",
      "dimensions": {
        "weight": {
          "value": 1.2,
          "unit": "GRM"
        },
        "length": {
          "value": 1.2,
          "unit": "MTR"
        },
        "width": {
          "value": 1.2,
          "unit": "MTR"
        },
        "height": {
          "value": 1.2,
          "unit": "MTR"
        },
        "volume": {
          "value": 1.2,
          "unit": "STL"
        }
      },
      "materialUsed": [
        {
          "name": "Recycled cardboard",
          "originCountry": {
            "countryCode": "FR"
          },
          "materialType": {
            "code": "481910",
            "name": "Corrugated paper board",
            "schemeID": "https://vocabulary.uncefact.org/CPC",
            "schemeName": "CPC"
          },
          "massFraction": 0.95
        }
      ],
      "performanceClaim": [
        {
          "claimedPerformance": [
            {
              "measure": {
                "value": 1.2,
                "unit": "KGM"
              }
            }
          ],
          "evidence": [
            {
              "linkURL": "https://brand.example.com/products/hiking-boots/front.jpg",
              "linkName": "Front view",
              "digestMultibase": "zQmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
              "mediaType": "image/jpeg",
              "linkType": "productImage"
            }
          ]
        }
      ]
    },
    "productLabel": [
      {
        "name": "CE marking",
        "imageData": "https://brand.example.com/labels/ce-mark.png",
        "mediaType": "image/png"
      }
    ],
    "performanceClaim": [
      {
        "id": "https://brand.example.com/claims/waterproof-2026",
        "name": "Waterproof rating IPX7",
        "referenceCriteria": [
          {
            "id": "https://vocabulary.uncefact.org/criteria/ipx7",
            "name": "IPX7 immersion test"
          }
        ],
        "claimDate": "2026-01-15",
        "claimedPerformance": [
          {
            "metric": {
              "id": "https://example.org/metrics/water-resistance",
              "name": "Water resistance"
            },
            "measure": {
              "value": 1,
              "unit": "MTR"
            },
            "score": {
              "code": "IPX7"
            }
          }
        ],
        "conformityTopic": [
          {
            "id": "https://vocabulary.uncefact.org/conformity/environmental",
            "name": "Environmental"
          }
        ]
      }
    ]
  },
  "actions": [
    {
      "type": "circularity",
      "url": "https://example.com/authenticity-proof",
      "label": {
        "en-US": "Verify authenticity",
        "fr-FR": "Vérifier l'authenticité"
      },
      "description": {
        "en-US": "Verify authenticity",
        "fr-FR": "Vérifier l'authenticité"
      },
      "icon": "recycle"
    }
  ],
  "certificateUri": "https://certs.example.com/dpp/550e8400.jsonld",
  "certificateSignature": "z3FXQjecWufY46yg5abdVZsXqLhxhueuSoGgQRDH8z3Rn...",
  "certifiedPaths": [
    "brand",
    "gtin",
    "manufacturer.name"
  ],
  "contentHash": "0x94b7e2c1a9f04d3e8b16c5a2d90e7f4815263748a5b6c7d8e9f0a1b2c3d4e5f6"
}

Response

Signed Verifiable Credential (JSON-LD)

Changes

No recorded changes to this operation across all 1 revision of this API.