GETMethod GET/passport/{identifier}/vc/preview

This endpoint returns, without a signature and without recording anything, the verifiable credential envelope and the JSON-LD document that a given access tier would expose for a product's passport.

#Authorization

None for the public tier. This endpoint is then open, with no API key and no session.

The five other values of the access_tier parameter require an account session. From your server, present it in the header Authorization: Bearer <session token>. The access_token cookie opens the same tiers, only in a call that also carries an Origin or Referer header that we accept, that is, from our own pages. A partner API key does not work: this endpoint reads only a session token, in the Authorization header or in the cookie. An API key therefore opens no tier beyond public.

We serve here only the passports with public visibility. A passport reserved for the product's owner answers 404 on this endpoint, including for that owner, whereas GET /v1/passport/{identifier} serves it to them. A passport reserved for the brand is never returned here.

#Origin check

This endpoint refuses any call whose Origin or Referer header designates a domain that is not ours, with 403 Forbidden origin. The refusal does not look at the nature of the client: a program launched on your server that sends a Referer receives the same 403 as a web page.

Two rules for calling from your server.

• Do not send a Referer header. Most HTTP libraries send none until you ask for it.
• Present your session in Authorization: Bearer <session token>. A server call that relies on the access_token cookie is refused with 403 Origin or Referer header required.

Do not call this address from your visitor's browser: a JavaScript call launched from a page hosted anywhere other than with us is refused.

#Rate limit

600 calls per 60 second window, counted per calling network address.

This counter is shared by every read (GET) whose path starts with /passport. The calls you address to one of them therefore eat into the budget of the others. The /v1 prefix does not create a second budget: /v1/passport/1042/vc/preview and /passport/1042/vc/preview fill the same counter.

Every accepted response carries three headers.

A refusal returns 429, with those three headers and Retry-After. On this endpoint, Retry-After equals the duration of the window, that is 60 seconds.

#Path and query parameters

identifier accepts three forms, tried in this order.

You can write the serial number in lowercase or in uppercase. We reduce the characters that look alike to a single form before the lookup, so an I or an L entered by hand finds the 1, and an O finds the 0.

This endpoint resolves only the items still in the brand's catalog. An item destroyed on the chain, replaced by a later version or archived answers 404. GET /v1/passport/{identifier} behaves differently: it keeps serving the last published passport for those items.

#The six values of access_tier

These tiers do not form a scale. They describe six audiences whose needs differ. A recycler and a repairer see different data.

The fields the console writes at the root of the passport each have their own tier, named one by one: see Passport access rules.

This table describes the filter applied before the conversion to JSON-LD. Several of these sections stay absent from the document returned, because this endpoint does not convert them. The callout further down lists them all.

A brand can tighten or widen these lists for its own products. The values above are the ones that apply when it has changed nothing.

#The full address and the alias without /v1

GET https://api.sealtrust.io/v1/passport/{identifier}/vc/preview

The same endpoint also answers without the /v1 prefix, at https://api.sealtrust.io/passport/{identifier}/vc/preview. Both addresses call the same code. Use the /v1 form for a new integration.

#What this preview does not prove

A verifiable credential is a document that its issuer signs, and that anyone can check afterwards without asking us for anything again. This endpoint shows its shape before signing.

#Request body

None. This request has no body.

#Example request

Public preview of the credential of the item whose printed serial number is EXEMPLE00001.

curl -i "https://api.sealtrust.io/v1/passport/EXEMPLE00001/vc/preview?access_tier=public"

const url = new URL(
  "https://api.sealtrust.io/v1/passport/EXEMPLE00001/vc/preview",
);
url.searchParams.set("access_tier", "public");

const response = await fetch(url);

if (response.status === 404) {
  console.log("No public passport for this identifier.");
} else if (response.ok) {
  const apercu = await response.json();

  console.log("Issuer:", apercu.issuer);
  console.log("Credential type:", apercu.vct);
  console.log("Tier requested:", apercu.access_tier);
  console.log("Signed:", apercu.signed);

  const sujet = apercu.credentialSubject;
  console.log(sujet.name, sujet.gtin, sujet.brand.name);

  for (const propriete of sujet.additionalProperty ?? []) {
    console.log(propriete.name, propriete.value, propriete.unitText ?? "");
  }
} else {
  console.log(response.status, await response.json());
}

import requests

response = requests.get(
    "https://api.sealtrust.io/v1/passport/EXEMPLE00001/vc/preview",
    params={"access_tier": "public"},
    timeout=30,
)

if response.status_code == 404:
    print("No public passport for this identifier.")
elif response.ok:
    apercu = response.json()

    print("Issuer:", apercu["issuer"])
    print("Credential type:", apercu["vct"])
    print("Tier requested:", apercu["access_tier"])
    print("Signed:", apercu["signed"])

    sujet = apercu["credentialSubject"]
    print(sujet.get("name"), sujet.get("gtin"), sujet["brand"]["name"])

    for propriete in sujet.get("additionalProperty", []):
        print(propriete["name"], propriete["value"], propriete.get("unitText", ""))
else:
    print(response.status_code, response.json())

#Example response

HTTP code 200.

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://schema.sealtrust.io/dpp/v1"
  ],
  "type": ["VerifiableCredential", "DigitalProductPassport"],
  "issuer": "did:web:api.sealtrust.io:brand:4242",
  "vct": "https://schema.sealtrust.io/vct/digital-product-passport",
  "credentialSubject": {
    "@context": {
      "@vocab": "https://schema.org/",
      "gs1": "https://gs1.org/voc/",
      "espr": "https://data.europa.eu/espr/"
    },
    "@type": "Product",
    "identifier": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "gtin": "03701234567891",
    "name": "Example Model 001",
    "brand": {
      "@type": "Brand",
      "name": "Exemple SAS",
      "identifier": "00000000000000000000",
      "url": "https://example.example"
    },
    "countryOfOrigin": "FR",
    "material": [],
    "additionalProperty": [
      {
        "@type": "PropertyValue",
        "name": "Recyclability (EN 45555)",
        "value": 82,
        "unitText": "percent"
      },
      {
        "@type": "PropertyValue",
        "name": "gs1:recycledContentPercentage",
        "value": 35,
        "unitText": "percent"
      }
    ],
    "espr:compliance": {
      "@type": "espr:ComplianceDeclaration",
      "espr:euEsprCompliant": true,
      "espr:reachCompliant": true,
      "espr:ceMarking": true
    }
  },
  "access_tier": "public",
  "signed": false,
  "note": "Unsigned preview — POST /vc/issue to mint the signed SD-JWT-VC."
}

The response's access_tier field and the X-DPP-Access-Tier header both repeat the tier you requested. The call succeeds at the tier requested or fails with 401 or 403. There is no silent fallback to a lower tier.

The response carries Cache-Control: private, no-store at a professional tier, and public, max-age=60, s-maxage=300 at the public tier only. No shared cache therefore keeps a response obtained at a professional tier.

#The issuer field

It is the identity of the issuer, in did:web form. It takes two forms depending on what the brand has chosen.

The first form applies by default, and the brand has nothing to do to get it. The second requires the brand to declare its own domain and to publish its identity document there.

Read the value returned as it is. Do not rebuild it on your side: a brand can move from one form to the other.

#The credentialSubject field

It is the passport rendered in JSON-LD, with the Schema.org vocabulary, the GS1 web vocabulary and our ESPR extensions. It carries its own @context, which is an object, whereas the one at the top level is a list. The two coexist normally.

An entry of additionalProperty carries @type equal to PropertyValue, a name in English, a value, and a unitText when the quantity has a unit. The names are the ones of the vocabulary, for example Recyclability (EN 45555) or gs1:recycledContentPercentage. Hook your code on name, on the exact value, with no translation.

#Model or lot passport

A passport of a model, or of a production lot, is bound to no item. It therefore has no identifier to pass in {identifier}. Its unsigned preview is read at the GS1 address of the passport itself, next to the passport and its proof:

GET https://api.sealtrust.io/v1/passport/01/{gtin}/vc/preview
GET https://api.sealtrust.io/v1/passport/01/{gtin}/10/{lot}/vc/preview

The first address targets the passport of the model that carries this GTIN. The second targets the passport of lot {lot} of that model. Like the other addresses of this page, each one also answers without the /v1 prefix.

It is the only way to preview the credential of a brand on the Compliance offer, which registers no item.

The access tier, the authorization rules, the rate limit and the fields of the response are those of this page. The response adds two fields, and a third one for a lot.

The preview of a model or a lot carries the identity of the model only. In credentialSubject, identifier is null.

The address of a lot targets the passport of that lot only. A lot without a published passport answers 404, and never with the preview of the model.

#Errors

The body of an error response carries a detail field.

The code carries one last case, 422 with detail equal to Brand has no persisted id; cannot derive a did:web issuer. You will not meet it: every registered brand receives an issuer identity, did:web:api.sealtrust.io:brand:<number> when it has not declared its own domain.

#See also

• GET /passport/{identifier}/vc, retrieve the signed credential of the passport, in SD-JWT-VC format.
• GET /passport/{identifier}/vc/verify, check the credential's signature and read the disclosed data.
• GET /brand/{brand_id}/did.json, retrieve a brand's public signing keys.
• Publishing a digital product passport, publish, choose who sees which fields, export and have it verified.