GETMethod GET/brand/{brand_id}/did.json

You retrieve the public keys a brand uses to sign its digital product passports. By the end of this page, you will know how to request this document, find in it the key that signed a given credential, and understand what the absence of a key means.

Full address:

GET https://api.sealtrust.io/v1/brand/{brand_id}/did.json

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

This document is what a verifier goes and fetches on its own. The signed credential of a passport carries an issuer identifier of the form did:web:api.sealtrust.io:brand:4242. The public rule of the did:web format translates that identifier into the address https://api.sealtrust.io/brand/4242/did.json, that is, this endpoint. Any standard did:web library performs that translation without knowing anything about SealTrust.

#Authorization

None, this is a public endpoint. You send no API key, no session and no origin header. The response is the same for everyone.

The document contains public keys only. No private key ever leaves our system, and none can be reconstructed from this document.

#Rate limit

This endpoint has no limit of its own. It shares a general counter with the other routes that have no limit of their own, counted per calling network address over a 60 second window.

Handle the 429 code in your client and honor the Retry-After header it carries. The value of the general counter can change without notice, so do not hard-code any number in your code.

The response carries three headers that describe this counter.

This document changes only when the brand rotates its signing keys, which is rare. Keep a copy on your side. Refresh it when a credential carries a kid that your copy does not contain.

#Path and query parameters

This endpoint has no query parameter.

#Headers

No header is required.

#Request body

None. This request has no body.

#Example request

Identity document of the brand whose identifier is 4242.

curl -i https://api.sealtrust.io/v1/brand/4242/did.json

const reponse = await fetch(
  "https://api.sealtrust.io/v1/brand/4242/did.json",
);

if (reponse.status === 404) {
  console.log("Aucune marque ne porte cet identifiant.");
} else if (reponse.ok) {
  const document = await reponse.json();

  console.log("Identifiant de la marque :", document.id);
  console.log("Clefs publiées :", document.verificationMethod.length);

  for (const methode of document.verificationMethod) {
    console.log(methode.id, methode.type, methode.publicKeyJwk.crv);
  }

  // Find the key that signed a given credential.
  const kid = "did:web:api.sealtrust.io:brand:4242#key-2";
  const clef = document.verificationMethod.find((m) => m.id === kid);

  if (clef) {
    console.log("Clef de signature trouvée :", clef.publicKeyJwk);
  } else {
    console.log("Cette clef n'est plus publiée. Signature à rejeter.");
  }
} else {
  console.log(reponse.status, await reponse.json());
}

import requests

response = requests.get(
    "https://api.sealtrust.io/v1/brand/4242/did.json",
    timeout=30,
)

if response.status_code == 404:
    print("Aucune marque ne porte cet identifiant.")
elif response.ok:
    document = response.json()

    print("Identifiant de la marque :", document["id"])
    print("Clefs publiées :", len(document["verificationMethod"]))

    for methode in document["verificationMethod"]:
        print(methode["id"], methode["type"], methode["publicKeyJwk"]["crv"])

    # Find the key that signed a given credential.
    kid = "did:web:api.sealtrust.io:brand:4242#key-2"
    clef = next(
        (m for m in document["verificationMethod"] if m["id"] == kid),
        None,
    )

    if clef:
        print("Clef de signature trouvée :", clef["publicKeyJwk"])
    else:
        print("Cette clef n'est plus publiée. Signature à rejeter.")
else:
    print(response.status_code, response.json())

#Example response

HTTP code 200. The body is JSON, served with the header Content-Type: application/json.

Here, the brand Exemple SAS has rotated its key once. Both versions remain published, so the credentials signed under the older one remain verifiable.

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:api.sealtrust.io:brand:4242",
  "verificationMethod": [
    {
      "id": "did:web:api.sealtrust.io:brand:4242#key-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:api.sealtrust.io:brand:4242",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "y": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
      }
    },
    {
      "id": "did:web:api.sealtrust.io:brand:4242#key-2",
      "type": "JsonWebKey2020",
      "controller": "did:web:api.sealtrust.io:brand:4242",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC",
        "y": "DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD"
      }
    }
  ],
  "assertionMethod": [
    "did:web:api.sealtrust.io:brand:4242#key-1",
    "did:web:api.sealtrust.io:brand:4242#key-2"
  ],
  "authentication": [
    "did:web:api.sealtrust.io:brand:4242#key-1",
    "did:web:api.sealtrust.io:brand:4242#key-2"
  ]
}

The five top-level fields are always present.

#An entry of verificationMethod

publicKeyJwk carries four fields: kty equals EC, crv equals P-256, x and y are the two coordinates of the public point, encoded in base64url. These values are passed as they are to a JWS verification library.

#Finding the key that signed a credential

The header of a passport credential carries a kid field. That kid equals exactly one of the id values of verificationMethod, for example did:web:api.sealtrust.io:brand:4242#key-2. You look that value up in the list, you take the matching publicKeyJwk, and you check the signature with the ES256 algorithm.

If the kid is not in the list, the signature must be rejected.

#What the absence of a key means

A revoked key is removed from the document. Every credential signed under that version stops being verifiable, and that is the intended result.

A key replaced by a more recent version stays published. It is no longer used to sign new credentials, and the older ones keep verifying.

verificationMethod can be an empty list, with assertionMethod and authentication empty too. That means the brand has not published any signing key yet. No credential from that brand is verifiable then.

#When the id field does not match the address called

A brand can carry its identity on its own domain name. The document's id field then equals did:web:<its domain>, and the reference document is found at https://<its domain>/.well-known/did.json.

In that case, take the id field of the credential you are verifying as your starting point, apply the did:web translation rule, and go and fetch the document at the resulting address. Never build the address yourself from the brand identifier.

#Errors

The body of an error response carries a detail field. Every response from this endpoint, successful or in error, carries an X-Request-Id header.

This endpoint returns neither 401 nor 403: it is public and reads no authorization.

#See also

• GET /.well-known/did.json, serve a brand's identity document on its own domain.
• 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.
• Trust and proofs, what each proof establishes and how a third party redoes the verification.