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 tier requires no account. The five 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 of an administrator of the product's brand opens the three professional tiers on its own products. The market surveillance authority role opens them as well, on every product. A client, repairer or recycler account that is still tied to the brand, a former administrator for instance, is not part of it: it receives 403, or the one tier of its accreditation.

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

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

This ceiling is shared by every read (GET) whose URL 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.

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

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 tier. 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 response = await fetch(url);

if (response.status === 404) {
  console.log("No signed attestation to check for this product.");
} else if (response.status === 403) {
  console.log(
    "Call refused: run this code from a server, never from a browser.",
  );
} else if (response.ok) {
  const result = await response.json();
  console.log(result.verified, result.error);
  console.log(result.issuer, result.key_version);
  console.log(result.credential_subject);
} else {
  console.log(response.status, await response.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("No signed attestation to check for this product.")
elif response.status_code == 403:
    print("Call refused: run this code from a server, never from a browser.")
elif response.ok:
    result = response.json()
    print(result["verified"], result["error"])
    print(result["issuer"], result["key_version"])
    print(result["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": "03701234567891",
      "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.

#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 credential is checked 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/verify
GET https://api.sealtrust.io/v1/passport/01/{gtin}/10/{lot}/vc/verify

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 have checked 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 credential of a model or a lot carries the identity of the model only. In its product block, uid_hash and token_id are 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 credential of the model.

#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.