.CopyPageActions-module__-WfCiq__principal,.CopyPageActions-module__-WfCiq__bascule{display:none}Voir en Markdown

Méthode GET/brand/{brand_id}/did.json

Récupérer le document d'identité d'une marque : la liste de ses clefs publiques de signature, au format did:web. Point d'entrée public.

Sur cette page

Autorisation
Plafond d'appels
Paramètres de chemin et de requête
En-têtes
Corps de la requête
Requête d'exemple
Réponse d'exemple
Une entrée de verificationMethod
Retrouver la clef qui a signé un justificatif
Ce que dit l'absence d'une clef
Le champ id correspond toujours à l'adresse appelée
Le même chemin sur le domaine partagé d'un revendeur
Erreurs
Voir aussi

Vous récupérez les clefs publiques avec lesquelles une marque signe ses passeports numériques de produit. En quittant cette page, vous saurez demander ce document, y retrouver la clef qui a signé un justificatif précis, et comprendre ce que veut dire l'absence d'une clef.

Adresse complète :

HTTP

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

Le même point d'entrée répond aussi sans le préfixe /v1, à https://api.sealtrust.io/brand/{brand_id}/did.json. Les deux adresses appellent le même code. Utilisez la forme /v1 pour une nouvelle intégration.

Ce document est ce qu'un vérificateur va chercher tout seul. Le justificatif signé d'un passeport porte un identifiant d'émetteur de la forme did:web:api.sealtrust.io:brand:4242. La règle publique du format did:web traduit cet identifiant en l'adresse https://api.sealtrust.io/brand/4242/did.json, c'est-à-dire ce point d'entrée. N'importe quelle bibliothèque did:web standard fait cette traduction sans rien connaître de SealTrust.

#Autorisation

Aucune, point d'entrée public. Vous n'envoyez ni clef d'API, ni session, ni en-tête d'origine. La réponse est la même pour tout le monde.

Le document ne contient que des clefs publiques. Aucune clef privée ne sort de notre système, et aucune n'est reconstructible depuis ce document.

#Plafond d'appels

600 appels par fenêtre de 60 secondes, comptés par adresse réseau appelante. Ce compteur est propre au document DID d'une marque : les clefs publiques servies sous /brand/ ont le leur. Le préfixe /v1 ne crée pas un second budget : /brand/{brand_id}/did.json et /v1/brand/{brand_id}/did.json partagent le même compteur.

Chaque réponse porte trois en-têtes.

#Paramètres de chemin et de requête

Nom	Type	Obligatoire	Description
`brand_id`	`integer`	oui	L'identifiant numérique de la marque. C'est le nombre qui suit `brand:` dans l'identifiant d'émetteur du justificatif signé.

Ce point d'entrée n'a aucun paramètre de requête.

Ici, la marque est nommée par son numéro, et non par le code public brand_code que prennent les autres routes. Ce numéro fait partie de l'identifiant did:web déjà signé dans les justificatifs émis. Or un document DID doit se trouver à l'adresse que son propre identifiant désigne. Cette adresse ne change donc pas.

#En-têtes

Aucun en-tête n'est requis.

#Corps de la requête

Aucun. Cette requête n'a pas de corps.

#Requête d'exemple

Document d'identité de la marque dont l'identifiant est 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);
  }

  // Retrouver la clef qui a signé un justificatif précis.
  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"])

    # Retrouver la clef qui a signé un justificatif précis.
    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())

#Réponse d'exemple

Code HTTP 200OK

Code HTTP 200. Le corps est du JSON, servi avec l'en-tête Content-Type: application/json.

Ici, la marque Exemple SAS a renouvelé sa clef une fois. Les deux versions restent publiées, donc les justificatifs signés sous l'ancienne restent vérifiables.

JSON

{
  "@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"
  ]
}

Les cinq champs de premier niveau sont toujours présents.

Champ	Type	Description
`@context`	`string[]`	Les deux vocabulaires qui donnent leur sens aux champs du document. Toujours ces deux valeurs, dans cet ordre.
`id`	`string`	L'identifiant de la marque, au format `did:web`. C'est la valeur que porte le champ émetteur d'un justificatif signé.
`verificationMethod`	`object[]`	Une entrée par clef publique publiée, de la plus ancienne version à la plus récente.
`assertionMethod`	`string[]`	Les identifiants des clefs autorisées à signer un justificatif. Reprend les mêmes entrées que `verificationMethod`, dans le même ordre.
`authentication`	`string[]`	Les identifiants des clefs autorisées à prouver le contrôle de cet identifiant. Reprend les mêmes entrées.

#Une entrée de `verificationMethod`

Champ	Type	Description
`id`	`string`	L'identifiant de la clef, de la forme `<identifiant de la marque>#key-<numéro de version>`.
`type`	`string`	Toujours `JsonWebKey2020`.
`controller`	`string`	L'identifiant de la marque qui contrôle cette clef. Vaut toujours le champ `id` du document.
`publicKeyJwk`	`object`	La clef publique elle-même, au format JWK.

publicKeyJwk porte quatre champs : kty vaut EC, crv vaut P-256, x et y sont les deux coordonnées du point public, encodées en base64url. Ces valeurs se passent telles quelles à une bibliothèque de vérification JWS.

#Retrouver la clef qui a signé un justificatif

L'en-tête d'un justificatif de passeport porte un champ kid. Ce kid vaut exactement l'un des id de verificationMethod, par exemple did:web:api.sealtrust.io:brand:4242#key-2. Vous cherchez cette valeur dans la liste, vous prenez le publicKeyJwk correspondant, et vous vérifiez la signature avec l'algorithme ES256.

Si le kid ne figure pas dans la liste, la signature doit être rejetée.

#Ce que dit l'absence d'une clef

Une clef révoquée sort du document. Tous les justificatifs signés sous cette version cessent d'être vérifiables, et c'est le résultat voulu.

Une clef remplacée par une version plus récente reste publiée. Elle n'est plus utilisée pour signer de nouveaux justificatifs, et les anciens continuent de se vérifier.

verificationMethod peut être une liste vide, avec assertionMethod et authentication vides eux aussi. Cela veut dire que la marque n'a encore publié aucune clef de signature. Aucun justificatif de cette marque n'est alors vérifiable.

#Le champ `id` correspond toujours à l'adresse appelée

Ce point d'entrée rend toujours un document dont le champ id vaut did:web:api.sealtrust.io:brand:<brand_id>, exactement l'identifiant que la règle de traduction did:web fait correspondre à l'adresse que vous venez d'appeler. Vous pouvez donc contrôler cette égalité, et rejeter le document si elle n'est pas vérifiée.

C'est vrai même quand la marque porte par ailleurs son identité sur son propre nom de domaine. Dans ce cas elle signe ses nouveaux justificatifs sous did:web:<son domaine>, mais les justificatifs qu'elle avait signés sous l'identifiant ci-dessus restent vérifiables ici, pour toujours. C'est voulu : ces justificatifs sont sur des objets déjà vendus, personne ne peut les re-signer.

Une marque peut donc avoir deux documents d'identité en même temps, sous deux adresses différentes, chacun portant l'identifiant de son adresse. Rien ne s'y oppose : chaque justificatif désigne lui-même celui qui le concerne.

#Le même chemin sur le domaine partagé d'un revendeur

Un revendeur peut servir toutes ses marques clientes sous un seul domaine, par exemple passeports.revendeur.com. Une marque cliente qui signe sous did:web:passeports.revendeur.com:brand:4242 fait traduire son identifiant en https://passeports.revendeur.com/brand/4242/did.json, et c'est ce même point d'entrée qui répond.

Sur ce domaine, le champ id du document vaut alors did:web:passeports.revendeur.com:brand:4242 : toujours l'identifiant de l'adresse appelée. Et le domaine ne répond que pour les marques que notre base rattache à ce revendeur. Pour toute autre marque, il rend 404, même si elle existe.

Sur le domaine propre d'une marque, en revanche, ce chemin rend 404 pour tout identifiant, le sien compris. Nous n'émettons aucun identifiant de la forme did:web:<domaine de la marque>:brand:<id>, donc aucun document servi à cette adresse ne pourrait porter l'identifiant de l'adresse appelée. L'identité d'une marque sur son propre domaine se lit à /.well-known/did.json.

#Erreurs

Le corps d'une réponse d'erreur porte un champ detail. Toute réponse de ce point d'entrée, réussie ou en erreur, porte un en-tête X-Request-Id.

Code	Condition	Que faire
404	Aucune marque ne porte cet identifiant, ou l'appel arrive sur le domaine partagé d'un revendeur qui ne sert pas cette marque, ou sur le domaine propre d'une marque. `detail` vaut `Brand not found`.	Vérifiez le nombre qui suit `brand:` dans l'identifiant d'émetteur. Rejetez la signature : un émetteur dont le document d'identité est introuvable ne prouve rien.
422	La valeur envoyée dans le chemin n'est pas un nombre entier. `detail` porte la liste des erreurs de validation, avec le nom du paramètre en cause.	Corrigez l'identifiant. Un identifiant de marque s'écrit uniquement en chiffres.
422	Le document d'identité de la marque trouvée ne peut pas être construit.	Signalez-le au support en indiquant l'identifiant appelé. Vous ne pouvez rien corriger de votre côté.
500	Une erreur inattendue s'est produite pendant le traitement de votre appel. `detail` vaut `Internal Server Error`.	Réessayez. Si l'erreur persiste, contactez le support en indiquant la valeur de `X-Request-Id`.

Ce point d'entrée ne renvoie ni 401, ni 403 : il est public et ne lit aucune autorisation.

#Voir aussi

GET /.well-known/did.json, servir le document d'identité d'une marque sur son propre domaine.
GET /passport/{identifier}/vc, récupérer le justificatif signé du passeport, au format SD-JWT-VC.
GET /passport/{identifier}/vc/verify, contrôler la signature du justificatif et lire les données révélées.
Confiance et preuves, ce que chaque preuve établit et comment un tiers refait la vérification.

Cette page vous a-t-elle été utile ?

Votre réponse ouvre un courriel pré-rempli dans votre messagerie, à destination de contact@sealtrust.io. Vous le relisez avant de l'envoyer.

Proposer une correction Signaler un problème

GETMéthode GET/brand/{brand_id}/did.json