---
title: "Build a signed Verifiable Credential (self-hosted certificate)"
method: POST
path: "/v1/dpp/passports/build-vc"
tags: ["DPP"]
---

# Build a signed Verifiable Credential (self-hosted certificate)

`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`

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.

## Request body

- CreateDppPassportDto
  - `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`.
  - `webPageUrl` string, 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.
  - `product` object, required
    - `type` unknown[]
      - unknown
    - `name` string, required: Commercial name of the product.
    - `description` string, nullable: Marketing description of the product. Null when absent (nullable column).
    - `modelNumber` string, nullable: Manufacturer model reference / SKU. Required at `batch` and `item` granularity to link to the parent `model` passport. Null when absent (nullable column).
    - `batchNumber` string, nullable: Production batch or lot identifier. Required at `item` granularity to link to the parent `batch` passport. Null at `model` granularity (nullable column).
    - `itemNumber` string, nullable: Individual serial number. Required at `item` granularity to identify a single physical unit. Null at `model`/`batch` granularity (nullable column).
    - `idGranularity` 'model' | 'batch' | 'item', required: Passport granularity: `model` = product template, `batch` = production lot, `item` = individual serialized unit.
    - `productImage` object: Primary product image shown in the passport viewer.
      - `linkURL` string, required: Absolute URL of the linked resource (RFC 3986).
      - `linkName` string, required: Human-readable label shown to the user for this link.
      - `digestMultibase` string: Multibase-encoded hash of the target resource, allowing consumers to verify the content has not been tampered with. Format: https://www.w3.org/TR/vc-data-integrity/#multibase-0.
      - `mediaType` string: IANA media type of the linked resource (e.g. `application/pdf`). See https://mimetype.io/.
      - `linkType` string: Semantic relationship with the current resource, typically a UNTP link-type code (e.g. `certificate`, `manual`).
    - `characteristics` object: Free-form dictionary of technical characteristics: each entry maps a human-readable label in the source-data language (e.g. « type de canne ») to a plain-text value with its units (e.g. « 1,80 m »). Product-specific — no fixed vocabulary.
    - `productCategory` object[]: Product categories against external classification schemes (CPC, HS, NACE, …). Typically non-empty.
      - `code` string, required: Classification code value within the referenced scheme (e.g. `6109.10` for CPC).
      - `name` string, required: Human-readable label corresponding to the code.
      - `definition` string: Optional long-form definition of the classification entry.
      - `schemeID` string, required: Identifier of the classification scheme (e.g. `https://vocabulary.uncefact.org/cpc`).
      - `schemeName` string, required: Human-readable name of the classification scheme (e.g. "UN CPC", "HS 2022").
    - `relatedDocument` object[]: Related documents (user manuals, datasheets, certificates, …).
      - `linkURL` string, required: Absolute URL of the linked resource (RFC 3986).
      - `linkName` string, required: Human-readable label shown to the user for this link.
      - `digestMultibase` string: Multibase-encoded hash of the target resource, allowing consumers to verify the content has not been tampered with. Format: https://www.w3.org/TR/vc-data-integrity/#multibase-0.
      - `mediaType` string: IANA media type of the linked resource (e.g. `application/pdf`). See https://mimetype.io/.
      - `linkType` string: Semantic relationship with the current resource, typically a UNTP link-type code (e.g. `certificate`, `manual`).
    - `relatedParty` object[]: Parties involved in the product lifecycle, each with its role (manufacturer, distributor, …).
      - `role` 'owner' | 'producer' | 'manufacturer' | 'processor' | 'remanufacturer' | 'recycler' | 'operator' | 'serviceProvider' | 'inspector' | 'certifier' | 'logisticsProvider' | 'carrier' | 'consignor' | 'consignee' | 'importer' | 'exporter' | 'distributor' | 'retailer' | 'brandOwner' | 'regulator', required: Role taken by the party with respect to the product. Values follow the UNTP `PartyRole` vocabulary.
      - `party` object, required: The party assuming the role.
        - `type` unknown[]
          - unknown
        - `id` string, required: Globally unique identifier of the party (typically an URI, DID, or GS1 GLN URL).
        - `name` string, required: Legal or trading name of the party.
        - `description` string: Free-form description of the party.
        - `registeredId` string: Registered legal identifier (e.g. SIRET, VAT number, GLN) as assigned by `idScheme`.
        - `idScheme` object: Identifier scheme describing how to interpret `registeredId`.
          - `type` unknown[]
            - unknown
          - `id` string, required: URI of the identifier scheme (e.g. `https://id.gs1.org/gln/`).
          - `name` string, required: Human-readable name of the identifier scheme (e.g. "GS1 GLN").
        - `registrationCountry` object: Country where the party is legally registered (may differ from the party’s operating location).
          - `countryCode` string, required: ISO 3166-1 alpha-2 country code as defined by the UNCEFACT vocabulary (https://vocabulary.uncefact.org/CountryId#).
          - `countryName` string: Optional localized country name; informational only, the code is the authoritative identifier.
        - `partyAddress` object: Postal address of the party.
          - `streetAddress` string, required: Street name and number, or equivalent line-1 of the address.
          - `postalCode` string, required: Postal or ZIP code. String-typed to preserve leading zeros and non-numeric formats.
          - `addressLocality` string, required: City or locality of the address.
          - `addressRegion` string, required: State, region, or province. Prefer ISO 3166-2 subdivision codes when known.
          - `addressCountry` object, required: Country of the address, as a UNTP `Country` reference.
            - `countryCode` string, required: ISO 3166-1 alpha-2 country code as defined by the UNCEFACT vocabulary (https://vocabulary.uncefact.org/CountryId#).
            - `countryName` string: Optional localized country name; informational only, the code is the authoritative identifier.
        - `organisationWebsite` string: Public website URL of the party.
        - `industryCategory` object[]: Industry classifications the party belongs to (e.g. NACE, ISIC codes).
          - `code` string, required: Classification code value within the referenced scheme (e.g. `6109.10` for CPC).
          - `name` string, required: Human-readable label corresponding to the code.
          - `definition` string: Optional long-form definition of the classification entry.
          - `schemeID` string, required: Identifier of the classification scheme (e.g. `https://vocabulary.uncefact.org/cpc`).
          - `schemeName` string, required: Human-readable name of the classification scheme (e.g. "UN CPC", "HS 2022").
    - `producedAtFacility` object
      - `type` unknown[]
        - unknown
      - `id` string: URI identifying the production facility.
      - `name` string: Commercial or trading name of the physical site where production took place — a plant, workshop or assembly line. Not the manufacturer, brand or vendor: a company name alone does not identify a site.
      - `registeredId` string: Legal identifier of the facility (e.g. GS1 GLN, national registry number).
    - `productionDate` union: Date the product (or batch / item) was physically manufactured (ISO 8601 `YYYY-MM-DD`). Not a record timestamp: a catalogue entry's creation, update or publication date is unrelated to when the goods were made.
      - string, date
      - string, date-time
    - `expiryDate` union: Date the product expires or is no longer recommended for use (ISO 8601 `YYYY-MM-DD`). Absent when not applicable.
      - string, date
      - string, date-time
    - `countryOfProduction` object
      - `countryCode` string: ISO 3166-1 alpha-2 country code as defined by the UNCEFACT vocabulary (https://vocabulary.uncefact.org/CountryId#).
      - `countryName` string: Optional localized country name; informational only, the code is the authoritative identifier.
    - `dimensions` object
      - `weight` object
        - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
        - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
        - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
        - `unit` string: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
      - `length` object
        - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
        - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
        - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
        - `unit` string: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
      - `width` object
        - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
        - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
        - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
        - `unit` string: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
      - `height` object
        - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
        - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
        - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
        - `unit` string: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
      - `volume` object
        - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
        - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
        - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
        - `unit` string: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
    - `materialProvenance` object[]: Breakdown of the materials composing the product, with origins and recycled content.
      - `name` string, required: Commercial or common name of the material (e.g. "Organic cotton").
      - `originCountry` object, required: Country where the material was harvested or produced.
        - `countryCode` string, required: ISO 3166-1 alpha-2 country code as defined by the UNCEFACT vocabulary (https://vocabulary.uncefact.org/CountryId#).
        - `countryName` string: Optional localized country name; informational only, the code is the authoritative identifier.
      - `materialType` object, required: Classification of the material against an external scheme (e.g. ECHA, CAS).
        - `code` string, required: Classification code value within the referenced scheme (e.g. `6109.10` for CPC).
        - `name` string, required: Human-readable label corresponding to the code.
        - `definition` string: Optional long-form definition of the classification entry.
        - `schemeID` string, required: Identifier of the classification scheme (e.g. `https://vocabulary.uncefact.org/cpc`).
        - `schemeName` string, required: Human-readable name of the classification scheme (e.g. "UN CPC", "HS 2022").
      - `mass` object: Absolute mass of the material, when known.
        - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
        - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
        - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
        - `unit` string, required: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
      - `massFraction` number, required: Share of the product mass represented by this material, expressed as a ratio in `[0, 1]` (e.g. `0.75` for 75%).
      - `recycledMassFraction` number: Share of `mass` that is post-consumer or post-industrial recycled content, expressed as a ratio in `[0, 1]`.
      - `hazardous` boolean: When `true`, the material is classified as hazardous under applicable regulations (e.g. REACH, CLP).
      - `symbol` object: Optional pictogram or labelling symbol associated with the material.
        - `name` string, required: Short label used to identify the image (e.g. "Front view").
        - `description` string: Optional longer description of the image content.
        - `imageData` string, required: Either a `data:` URL with the base64-encoded bytes, or an absolute URL pointing to the image resource.
        - `mediaType` string, required: IANA media type of the image (e.g. `image/png`, `image/webp`). See https://mimetype.io/.
      - `materialSafetyInformation` object: Link to the material safety data sheet (SDS) or equivalent document.
        - `linkURL` string, required: Absolute URL of the linked resource (RFC 3986).
        - `linkName` string, required: Human-readable label shown to the user for this link.
        - `digestMultibase` string: Multibase-encoded hash of the target resource, allowing consumers to verify the content has not been tampered with. Format: https://www.w3.org/TR/vc-data-integrity/#multibase-0.
        - `mediaType` string: IANA media type of the linked resource (e.g. `application/pdf`). See https://mimetype.io/.
        - `linkType` string: Semantic relationship with the current resource, typically a UNTP link-type code (e.g. `certificate`, `manual`).
    - `packaging` object
      - `description` string, required: Free-form description of the packaging (e.g. "cardboard box with PE inner bag").
      - `dimensions` object, required
        - `weight` object
          - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
          - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
          - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
          - `unit` string: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
        - `length` object
          - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
          - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
          - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
          - `unit` string: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
        - `width` object
          - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
          - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
          - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
          - `unit` string: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
        - `height` object
          - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
          - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
          - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
          - `unit` string: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
        - `volume` object
          - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
          - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
          - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
          - `unit` string: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
      - `materialUsed` object[], required: Materials composing the packaging, with their mass fractions and recycled content.
        - `name` string, required: Commercial or common name of the material (e.g. "Organic cotton").
        - `originCountry` object, required: Country where the material was harvested or produced.
          - `countryCode` string, required: ISO 3166-1 alpha-2 country code as defined by the UNCEFACT vocabulary (https://vocabulary.uncefact.org/CountryId#).
          - `countryName` string: Optional localized country name; informational only, the code is the authoritative identifier.
        - `materialType` object, required: Classification of the material against an external scheme (e.g. ECHA, CAS).
          - `code` string, required: Classification code value within the referenced scheme (e.g. `6109.10` for CPC).
          - `name` string, required: Human-readable label corresponding to the code.
          - `definition` string: Optional long-form definition of the classification entry.
          - `schemeID` string, required: Identifier of the classification scheme (e.g. `https://vocabulary.uncefact.org/cpc`).
          - `schemeName` string, required: Human-readable name of the classification scheme (e.g. "UN CPC", "HS 2022").
        - `mass` object: Absolute mass of the material, when known.
          - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
          - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
          - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
          - `unit` string, required: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
        - `massFraction` number, required: Share of the product mass represented by this material, expressed as a ratio in `[0, 1]` (e.g. `0.75` for 75%).
        - `recycledMassFraction` number: Share of `mass` that is post-consumer or post-industrial recycled content, expressed as a ratio in `[0, 1]`.
        - `hazardous` boolean: When `true`, the material is classified as hazardous under applicable regulations (e.g. REACH, CLP).
        - `symbol` object: Optional pictogram or labelling symbol associated with the material.
          - `name` string, required: Short label used to identify the image (e.g. "Front view").
          - `description` string: Optional longer description of the image content.
          - `imageData` string, required: Either a `data:` URL with the base64-encoded bytes, or an absolute URL pointing to the image resource.
          - `mediaType` string, required: IANA media type of the image (e.g. `image/png`, `image/webp`). See https://mimetype.io/.
        - `materialSafetyInformation` object: Link to the material safety data sheet (SDS) or equivalent document.
          - `linkURL` string, required: Absolute URL of the linked resource (RFC 3986).
          - `linkName` string, required: Human-readable label shown to the user for this link.
          - `digestMultibase` string: Multibase-encoded hash of the target resource, allowing consumers to verify the content has not been tampered with. Format: https://www.w3.org/TR/vc-data-integrity/#multibase-0.
          - `mediaType` string: IANA media type of the linked resource (e.g. `application/pdf`). See https://mimetype.io/.
          - `linkType` string: Semantic relationship with the current resource, typically a UNTP link-type code (e.g. `certificate`, `manual`).
      - `packageLabel` object[]: Images of the labelling printed on the package.
        - `name` string, required: Short label used to identify the image (e.g. "Front view").
        - `description` string: Optional longer description of the image content.
        - `imageData` string, required: Either a `data:` URL with the base64-encoded bytes, or an absolute URL pointing to the image resource.
        - `mediaType` string, required: IANA media type of the image (e.g. `image/png`, `image/webp`). See https://mimetype.io/.
      - `performanceClaim` object[]: Claims specifically concerning the packaging (e.g. recyclability, compostability).
        - `type` unknown[]
          - unknown
        - `id` string, required: URI uniquely identifying the claim within the issuer’s system.
        - `name` string, required: Short name of the claim (e.g. "Organic certification").
        - `description` string: Long-form description of what is being claimed.
        - `referenceCriteria` object[], required: Criteria referenced by the claim. Non-empty in practice.
          - `type` unknown[]
            - unknown
          - `id` string, required: URI identifying the criterion evaluated.
          - `name` string, required: Human-readable name of the criterion.
        - `referenceRegulation` object[]: Regulations the claim maps onto, when applicable.
          - `type` unknown[]
            - unknown
          - `id` string, required: URI identifying the regulation (e.g. "https://eur-lex.europa.eu/eli/reg/2019/1020").
          - `name` string, required: Human-readable name of the regulation (e.g. "EU 2019/1020").
        - `referenceStandard` object[]: Voluntary standards the claim aligns with.
          - `type` unknown[]
            - unknown
          - `id` string, required: URI identifying the standard (e.g. "https://www.iso.org/standard/14001").
          - `name` string, required: Human-readable name of the standard (e.g. "ISO 14001").
        - `claimDate` union: Date on which the claim was issued by the credential issuer (ISO 8601 `YYYY-MM-DD`).
          - string, date
          - string, date-time
        - `applicablePeriod` object: Period during which the claim is valid. When omitted, the claim is considered open-ended until the credential expires.
          - `type` unknown[]
            - unknown
          - `startDate` union: Inclusive start date of the period (ISO 8601 `YYYY-MM-DD`).
            - string, date
            - string, date-time
          - `endDate` union: Inclusive end date of the period (ISO 8601 `YYYY-MM-DD`).
            - string, date
            - string, date-time
          - `periodInformation` string: Free-form note about the period (e.g. "harvest season 2025").
        - `claimedPerformance` object[], required: Supporting performance measurements backing the claim. Typically contains one entry per metric.
          - `type` unknown[]
            - unknown
          - `metric` object, required: Definition of the performance metric being reported.
            - `type` unknown[]
              - …
            - `id` string, required: URI uniquely identifying the metric (e.g. `https://example.org/metrics/co2e`).
            - `name` string, required: Human-readable name of the metric (e.g. "Carbon footprint").
          - `measure` object, required: Quantitative value achieved against the metric.
            - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
            - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
            - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
            - `unit` string, required: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
          - `score` object, required: Qualitative score corresponding to the measure (e.g. energy class).
            - `type` unknown[]
              - …
            - `code` string, required: Symbolic score value (e.g. `A+`, `B`, `5-stars`). Interpreted according to the referenced metric.
            - `rank` integer: Numerical rank (`1` = best), allowing consumers to order or compare scores consistently.
            - `definition` string: Optional description of the meaning of this score level.
        - `evidence` object[]: Links to third-party evidence documents (test reports, audit certificates, …).
          - `linkURL` string, required: Absolute URL of the linked resource (RFC 3986).
          - `linkName` string, required: Human-readable label shown to the user for this link.
          - `digestMultibase` string: Multibase-encoded hash of the target resource, allowing consumers to verify the content has not been tampered with. Format: https://www.w3.org/TR/vc-data-integrity/#multibase-0.
          - `mediaType` string: IANA media type of the linked resource (e.g. `application/pdf`). See https://mimetype.io/.
          - `linkType` string: Semantic relationship with the current resource, typically a UNTP link-type code (e.g. `certificate`, `manual`).
        - `conformityTopic` object[], required: Thematic topic the claim falls under (environmental, social, …).
          - `type` unknown[]
            - unknown
          - `id` string, required: URI identifying the conformity topic in the UNTP vocabulary.
          - `name` string, required: Human-readable topic name (e.g. "Environmental", "Social").
          - `definition` string: Optional definition of the topic scope.
    - `productLabel` object[]: Images of the regulatory or commercial labels printed on the product.
      - `name` string, required: Short label used to identify the image (e.g. "Front view").
      - `description` string: Optional longer description of the image content.
      - `imageData` string, required: Either a `data:` URL with the base64-encoded bytes, or an absolute URL pointing to the image resource.
      - `mediaType` string, required: IANA media type of the image (e.g. `image/png`, `image/webp`). See https://mimetype.io/.
    - `performanceClaim` object[]: Headline performance claim attached to the product (e.g. energy class).
      - `type` unknown[]
        - unknown
      - `id` string, required: URI uniquely identifying the claim within the issuer’s system.
      - `name` string, required: Short name of the claim (e.g. "Organic certification").
      - `description` string: Long-form description of what is being claimed.
      - `referenceCriteria` object[], required: Criteria referenced by the claim. Non-empty in practice.
        - `type` unknown[]
          - unknown
        - `id` string, required: URI identifying the criterion evaluated.
        - `name` string, required: Human-readable name of the criterion.
      - `referenceRegulation` object[]: Regulations the claim maps onto, when applicable.
        - `type` unknown[]
          - unknown
        - `id` string, required: URI identifying the regulation (e.g. "https://eur-lex.europa.eu/eli/reg/2019/1020").
        - `name` string, required: Human-readable name of the regulation (e.g. "EU 2019/1020").
      - `referenceStandard` object[]: Voluntary standards the claim aligns with.
        - `type` unknown[]
          - unknown
        - `id` string, required: URI identifying the standard (e.g. "https://www.iso.org/standard/14001").
        - `name` string, required: Human-readable name of the standard (e.g. "ISO 14001").
      - `claimDate` union: Date on which the claim was issued by the credential issuer (ISO 8601 `YYYY-MM-DD`).
        - string, date
        - string, date-time
      - `applicablePeriod` object: Period during which the claim is valid. When omitted, the claim is considered open-ended until the credential expires.
        - `type` unknown[]
          - unknown
        - `startDate` union: Inclusive start date of the period (ISO 8601 `YYYY-MM-DD`).
          - string, date
          - string, date-time
        - `endDate` union: Inclusive end date of the period (ISO 8601 `YYYY-MM-DD`).
          - string, date
          - string, date-time
        - `periodInformation` string: Free-form note about the period (e.g. "harvest season 2025").
      - `claimedPerformance` object[], required: Supporting performance measurements backing the claim. Typically contains one entry per metric.
        - `type` unknown[]
          - unknown
        - `metric` object, required: Definition of the performance metric being reported.
          - `type` unknown[]
            - unknown
          - `id` string, required: URI uniquely identifying the metric (e.g. `https://example.org/metrics/co2e`).
          - `name` string, required: Human-readable name of the metric (e.g. "Carbon footprint").
        - `measure` object, required: Quantitative value achieved against the metric.
          - `value` number, required: Numerical magnitude of the measure, expressed in `unit`.
          - `upperTolerance` number: Absolute upper deviation accepted around `value`, in the same unit.
          - `lowerTolerance` number: Absolute lower deviation accepted around `value`, in the same unit.
          - `unit` string, required: UN/ECE Recommendation 20 unit of measure code (e.g. `KGM`, `MTR`). Full list: https://vocabulary.uncefact.org/UnitMeasureCode#.
        - `score` object, required: Qualitative score corresponding to the measure (e.g. energy class).
          - `type` unknown[]
            - unknown
          - `code` string, required: Symbolic score value (e.g. `A+`, `B`, `5-stars`). Interpreted according to the referenced metric.
          - `rank` integer: Numerical rank (`1` = best), allowing consumers to order or compare scores consistently.
          - `definition` string: Optional description of the meaning of this score level.
      - `evidence` object[]: Links to third-party evidence documents (test reports, audit certificates, …).
        - `linkURL` string, required: Absolute URL of the linked resource (RFC 3986).
        - `linkName` string, required: Human-readable label shown to the user for this link.
        - `digestMultibase` string: Multibase-encoded hash of the target resource, allowing consumers to verify the content has not been tampered with. Format: https://www.w3.org/TR/vc-data-integrity/#multibase-0.
        - `mediaType` string: IANA media type of the linked resource (e.g. `application/pdf`). See https://mimetype.io/.
        - `linkType` string: Semantic relationship with the current resource, typically a UNTP link-type code (e.g. `certificate`, `manual`).
      - `conformityTopic` object[], required: Thematic topic the claim falls under (environmental, social, …).
        - `type` unknown[]
          - unknown
        - `id` string, required: URI identifying the conformity topic in the UNTP vocabulary.
        - `name` string, required: Human-readable topic name (e.g. "Environmental", "Social").
        - `definition` string: Optional definition of the topic scope.
  - `data` object: Free-form business payload (attributes, traceability, compliance fields, ...). Consumed as the source object for the certified snapshot — see `certifiedPaths`.
  - `actions` object[]: Public actions (links / buttons) rendered on the passport page (e.g. authenticity proof, care guide).
    - `id` string, uuid, required: Stable UUID v4 assigned server-side. Unique per application. Used to identify and update a specific action button.
    - `enabled` boolean, required: When `false`, the button is hidden on the public passport viewer. The `url` and `icon` fields are ignored.
    - `type` 'circularity' | 'marketing', required: Functional family of the action. The passport viewer renders one card per type (circularity services vs commercial offers).
    - `url` string: Absolute HTTPS URL the button points to. When empty or absent, the action is rendered as a non-clickable informational row on the passport viewer.
    - `label` object: Localized label displayed on the button, keyed by BCP 47 locale code. The DPP App resolves the active locale and falls back to the application default locale. The button is hidden when no label matches.
    - `description` object: Localized secondary line displayed under the label on the passport viewer, keyed by BCP 47 locale code (e.g. the program or offer the action belongs to). Resolved with the same locale rules as `label`. The line is omitted when absent.
    - `icon` string: Icon identifier for the button. Accepts a Lucide icon name in kebab-case (e.g. `"recycle"`, `"wrench"` — the viewer supports a curated subset and renders unknown names as plain text, so emojis also work) or an absolute HTTPS URL pointing to an SVG asset.
  - `certificateUri` string, 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.
  - `certificateSignature` string, 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.
  - `certifiedPaths` string[]: 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.
  - `allowedClaimEmail` string, email, nullable: Email address authorized to claim this item. Empty string is coerced to `null` (no restriction).
  - `allowedClaimPhoneNumber` string, e164, nullable: E.164 phone number authorized to claim this item. Empty string is coerced to `null` (no restriction).
  - `application` string, uuid, required
  - `contentHash` string: 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).

## Response `200`

Signed Verifiable Credential (JSON-LD)

## Other responses

- `422`: The passport content has nothing to certify

---

[API](https://skmtc.dev/keyban/apis/keyban-rest-apis.md) · [All operations](https://skmtc.dev/keyban/apis/keyban-rest-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/keyban/apis/keyban-rest-apis/revisions/0bb79a1da961?raw)