GETMethod GET/passport/{identifier}/vc

You retrieve the passport of a product as a digital credential signed by the brand. When you leave this page, you will know how to ask for that credential at the access tier that concerns you, how to read the six fields of the response, and where to find the public key that lets you check its signature without trusting us.

Full address:

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

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

The response is a JSON object of six fields. The passport itself sits in a single field, as a character string signed in the SD-JWT-VC format. To read the passport data as directly usable JSON, call GET /v1/passport/{identifier}.

#Authorization

None for the public tier. This endpoint is public at that tier only.

A partner API key opens nothing here. The tiers that ask for an identity are opened with a user account session token, never with an API key.

The five other values of the access_tier parameter require an account session, which you present 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 the products of that brand. 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.

The access tier rules are the same as those of the GET /v1/passport/{identifier} endpoint. This path therefore never gives access to more fields than the JSON read.

One difference separates the two paths. This endpoint only serves the passports whose visibility is public. A passport reserved for the owner or reserved for the brand is never returned here, not even to its owner.

#The origin check

Your server-to-server calls go through as they are. Two situations give a 403.

A call issued by a web page opened on a domain that is not ours carries an Origin or Referer header that we refuse. So do not call this endpoint from the browser of a visitor, call it from your server.

A call that carries the session cookie without an Origin or Referer header is refused as well. The session cookie only holds from a page served by one of our domains. From a server or from the command line, present the token in Authorization: Bearer.

#Rate limit

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

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

Every accepted response carries three headers.

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

#Path and query parameters

No header is required in the request.

#The three accepted forms of identifier

The identifier hash exists for a QR-only product just as for a product with an NFC chip. The server draws it at random for a QR product, it derives it from the identifier of the chip for an NFC product.

The server recognizes the form from the way it is written. It looks up a value that starts with 0x and is exactly 66 characters long as an identifier hash. It looks up any other value first as a token identifier. It tries the serial number last, when the first two lookups have returned nothing.

The server recognizes the identifier hash whatever the case. It also recognizes the serial number whatever the case, and it canonicalizes it the way the QR resolver does: it reads the letters I and L as a 1, the letter O as a 0. You can therefore send it a number copied by hand from a label.

This endpoint only resolves the products still in the catalog of the brand. An item destroyed on chain, replaced by a later version or withdrawn without replacement answers 404.

#The six values of access_tier

These tiers are different audiences, with no hierarchy between them. A recycler is not above a repairer. Each of the three professional tiers inherits the public tier and the end user tier, then adds what its trade calls for.

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 of the brand's own. The same rules apply here and on the JSON read.

The server refuses any other value with 422. It returns the tier actually served in the access_tier field of the response and in the X-DPP-Access-Tier header. Read one of the two rather than assuming it.

#Request body

None. This request has no body.

#Example request

Public credential of the product whose printed number is EXEMP1E00001.

curl -s "https://api.sealtrust.io/v1/passport/EXEMP1E00001/vc?access_tier=public"

const identifier = "EXEMP1E00001";

const url = new URL(
  `https://api.sealtrust.io/v1/passport/${encodeURIComponent(identifier)}/vc`,
);
url.searchParams.set("access_tier", "public");

const response = await fetch(url, { method: "GET" });

if (response.status === 403) {
  throw new Error(
    "Call refused: run this request from your server, never from a browser.",
  );
}
if (!response.ok) {
  throw new Error(`SealTrust replied ${response.status}`);
}

const justificatif = await response.json();

console.log(justificatif.issuer, justificatif.access_tier);
console.log(justificatif.format, justificatif.vct);

const segments = justificatif.sd_jwt_vc.split("~");
console.log("Signed token:", segments[0]);
console.log("Segments de divulgation :", segments.slice(1, -1).length);

import requests
from urllib.parse import quote

identifier = "EXEMP1E00001"

response = requests.get(
    f"https://api.sealtrust.io/v1/passport/{quote(identifier, safe='')}/vc",
    params={"access_tier": "public"},
    timeout=30,
)

if response.status_code == 403:
    raise SystemExit(
        "Call refused: run this request from your server, never from a browser."
    )
if not response.ok:
    raise SystemExit(f"SealTrust replied {response.status_code}")

justificatif = response.json()

print(justificatif["issuer"], justificatif["access_tier"])
print(justificatif["format"], justificatif["vct"])

segments = justificatif["sd_jwt_vc"].split("~")
print("Signed token:", segments[0])
print("Segments de divulgation :", len(segments[1:-1]))

The three tabs call the same address with the same values. The curl tab writes the raw response to standard output. The TypeScript and Python tabs extract the same fields from it, in the same order.

#Example response

HTTP status code 200.

The values below are fictitious. The signed token and the disclosure segments are shortened, a real token is several thousand characters long.

{
  "passport_id": 1,
  "issuer": "did:web:api.sealtrust.io:brand:4242",
  "vct": "https://schema.sealtrust.io/vct/digital-product-passport",
  "access_tier": "public",
  "format": "dc+sd-jwt",
  "sd_jwt_vc": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImRjK3NkLWp3dCIsImtpZCI6ImRpZDp3ZWI6YXBpLnNlYWx0cnVzdC5pbzpicmFuZDo0MjQyI2tleS0xIn0.RVhFTVBMRV9DSEFSR0VfVVRJTEU.RVhFTVBMRV9TSUdOQVRVUkU~"
}

#Response headers worth knowing

#Reading the sd_jwt_vc field

The content of sd_jwt_vc is a run of segments separated by the ~ character. The last segment is always empty, so the string ends with a ~.

<signed token>~<disclosure>~<disclosure>~

The first segment is a signed token in three parts, separated by dots. The header and the payload are encoded in base64url, without padding. You decode them without a key.

The header carries three values.

The payload carries the following fields.

A passport can cover a product model or one specific item. When the brand publishes a model passport, it holds for every item that shares the same product code, and the credential issued at that publication carries uid_hash and token_id at null in the product block: it designates no item in particular.

The following segments are the disclosures. Each one is an array of three elements encoded in base64url: a salt, the name of the field, its value. You decode them without a key. Their number depends on the tier asked for.

WyJFWEVNUExFMDAwMDAwMDAwMDAwMDAwMCIsInJlcGFpcmFiaWxpdHlfaW5kZXgiLDguMl0

That example segment decodes to ["EXEMPLE0000000000000000", "repairability_index", 8.2].

At the public tier, the response reveals nothing more than the fields always present in the signed document. The string is then reduced to the signed token followed by a ~. Each other tier adds the disclosures that concern it.

#Check the signature yourself

The issuer field carries a did:web identifier. It designates a public document that contains the public keys of the brand, expressed as JsonWebKey2020. The key to use is the one whose identifier matches the kid of the token header. That document contains only the keys that are not revoked, so a revoked key no longer appears in it.

An identifier of the form did:web:api.sealtrust.io:brand:4242 resolves to https://api.sealtrust.io/brand/4242/did.json. An identifier of the form did:web:id.exemple-sas.example resolves to https://id.exemple-sas.example/.well-known/did.json. A brand can host that document itself on its own domain, in which case the verification of its passports depends on none of our servers.

If you prefer the verification to be done for you, call GET /v1/passport/{identifier}/vc/verify.

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

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

#See also

• GET /passport/{identifier}/vc/preview, see, without a signature, what an access tier would expose.
• GET /passport/{identifier}/vc/verify, check the signature of the credential and read the data revealed.
• GET /brand/{brand_id}/did.json, retrieve the public signing keys of a brand.
• Publish a Digital Product Passport, publish, choose who sees which fields, export and have it verified.