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

You have the signature of a product's digital passport checked, and you get back the data that this signature covers. By the time you leave this page, you will know how to request this check from any product identifier, tell a check that fails apart from a request that fails, and know which data the response shows you depending on the access tier you request.

Full URL:

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

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

The passport is delivered in the SD-JWT-VC format, a signed credential in which each field can be revealed or withheld separately. The issuer is the brand, identified by a did:web decentralized identifier. This endpoint reassembles the credential at the access tier you request, checks its signature, and returns the revealed data to you.

#Authorization

No API key scope is checked on this endpoint. Two checks apply all the same: the origin of your call, then the access tier you request.

#Where you call from

Call this endpoint from your server.

We refuse with a 403 any call that carries an Origin or Referer header designating a domain other than ours. The detail field is then Forbidden origin. A browser always sets one of these two headers, so a web page hosted anywhere other than with us cannot call this URL from its visitor's browser.

The session cookie only works from a page served by one of our domains. We refuse with a 403 a call that carries this cookie without an Origin or Referer header, with detail set to Origin or Referer header required. From a server, present the session token in the Authorization: Bearer header.

#The tier you request

The public and end_user tiers require no account. The four other values of the access_tier parameter require an account session, presented through the Authorization: Bearer <session token> header or through the session cookie set at sign-in.

A session with access to the brand of the product opens the three professional tiers on its own products. The market surveillance authority role opens them as well, on every product.

A partner API key opens nothing here. The token received in the Authorization header is decoded as a user account session token, and an API key is not one. The read fails silently and the call goes on as an anonymous call.

#Rate limit

60 calls per 60 second slice, counted per calling IP address. The window is fixed.

This ceiling is shared by every URL that starts with /passport. The /passport/… and /v1/passport/… forms feed the same counter, the /v1 prefix does not create a second budget.

Every accepted response carries three headers that describe this counter.

Going over returns 429, with the same three headers and a Retry-After. On this endpoint, Retry-After is worth the length of the window, that is 60 seconds.

#Path and query parameters

#The three identifier forms accepted

The identifier hash exists for a QR only product as much as for a product with an NFC chip. The server draws it at random for a QR only product. It derives it from the identifier of the chip for a product with an NFC chip. Both forms therefore look the same and are requested in the same way.

We recognize the form from the way it is written. A value that starts with 0x and is exactly 66 characters long, we look up as an identifier hash. Any other value, we look up first as a token identifier, then as a serial number when the first lookup found nothing.

You write the identifier hash in whatever case you want. You write the serial number in whatever case you want as well, and we canonicalize it the way the QR resolver does: in it we read the letters I and L as a 1, the letter O as a 0. So you can copy by hand a number read on a label.

The certificate of authenticity number is not accepted here.

A product destroyed on the chain or withdrawn from the catalog no longer resolves through this endpoint, and the response is then 404.

#The six values of access_tier

These tiers are different audiences, with no hierarchy between them. Each of the three professional tiers inherits the public tier and the end user tier, then adds what its profession requires.

A brand can replace these rules with its own. The table above describes what applies in the absence of rules specific to the brand.

#Headers

No header is required for the public and end_user tiers. The five other tiers require the Authorization header or the session cookie. In every case, respect the origin rule described above.

#Request body

None. This request has no body.

#Example request

Check of the credential of the product whose printed number is EXEMPLE00001, at the public tier.

The three examples run from a server. None of them works in a visitor's browser: the browser sets an Origin header that we refuse, and you receive a 403.

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

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

const reponse = await fetch(url);

if (reponse.status === 404) {
  console.log("Aucune attestation signée à contrôler pour ce produit.");
} else if (reponse.status === 403) {
  console.log(
    "Appel refusé : exécutez ce code depuis un serveur, jamais depuis un navigateur.",
  );
} else if (reponse.ok) {
  const resultat = await reponse.json();
  console.log(resultat.verified, resultat.error);
  console.log(resultat.issuer, resultat.key_version);
  console.log(resultat.credential_subject);
} else {
  console.log(reponse.status, await reponse.json());
}

import requests

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

if response.status_code == 404:
    print("Aucune attestation signée à contrôler pour ce produit.")
elif response.status_code == 403:
    print("Appel refusé : exécutez ce code depuis un serveur, jamais depuis un navigateur.")
elif response.ok:
    resultat = response.json()
    print(resultat["verified"], resultat["error"])
    print(resultat["issuer"], resultat["key_version"])
    print(resultat["credential_subject"])
else:
    print(response.status_code, response.json())

#Example response

HTTP code 200. The signature is valid and the tier requested is public.

{
  "passport_id": 1,
  "issuer": "did:web:api.sealtrust.io:brand:4242",
  "vct": "https://schema.sealtrust.io/vct/digital-product-passport",
  "key_version": 1,
  "access_tier": "public",
  "verified": true,
  "error": null,
  "credential_subject": {
    "product_identity": {
      "gtin": "03701234567890",
      "model": "Cartable Exemple 32",
      "brand": "Exemple SAS",
      "made_in": "FR"
    },
    "compliance": {
      "eu_espr": true,
      "reach": true,
      "ce_marking": false
    },
    "circularity": {
      "recyclability_percentage": 62,
      "recycled_content_percentage": 0
    }
  }
}

The response has eight fields and nothing else.

#A check that fails is still a 200 response

That is the point to remember from this page. A check failure is not an HTTP error. The response stays 200 and carries the verdict.

{
  "passport_id": 1,
  "issuer": "did:web:api.sealtrust.io:brand:4242",
  "vct": "https://schema.sealtrust.io/vct/digital-product-passport",
  "key_version": 1,
  "access_tier": "public",
  "verified": false,
  "error": "verification_failed",
  "credential_subject": null
}

So always read verified. A 200 code says nothing on its own.

#What flips verified to false

The response does not say which of these causes applies. The error field is verification_failed in all of these cases.

#Checking the signature yourself

You are not required to ask us for this verdict. The brand publishes its public signing keys in a decentralized identity document, served publicly at GET https://api.sealtrust.io/brand/{brand_id}/did.json. A brand that hosts its identity on its own domain serves it at https://<its domain>/.well-known/did.json.

With that document and any off-the-shelf did:web and SD-JWT-VC library, you check the signature without going through us. That is what makes the passport enforceable without depending on our availability.

#Errors

The body of an error response carries a detail field.

The checks run in this order: origin of the call, resolution of the product, lookup of the published passport, check of the tier requested, presence of an issued credential, then identification of the issuing brand. The first step that fails gives the response.

#See also

• GET /passport/{identifier}/vc, retrieve the signed credential of the passport, in the SD-JWT-VC format.
• GET /passport/{identifier}/vc/preview, see, without a signature, what an access tier would expose.
• GET /brand/{brand_id}/did.json, retrieve the public signing keys of a brand.
• GET /.well-known/did.json, serve the identity document of a brand on its own domain.