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

Méthode GET/.well-known/did.json

Servir le document d'identité décentralisée d'une marque sur son propre nom de domaine, en mode délégué. Point d'entrée public, résolu d'après le nom d'hôte appelé.

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
Ce que contient la liste des clefs
Faire pointer votre domaine
Erreurs
Voir aussi

Vous récupérez le document d'identité décentralisée d'une marque, publié sous le nom de domaine de cette marque. Ce document liste les clefs publiques avec lesquelles la marque signe ses passeports numériques de produit. En quittant cette page, vous saurez appeler cette adresse, lire chaque champ du document, et distinguer un domaine qui n'est pas encore reconnu d'un domaine reconnu pour lequel aucune marque n'a été déclarée.

Adresse complète, avec un domaine d'exemple :

HTTP

GET https://id.exemple-sas.example/.well-known/did.json

Ce point d'entrée ne se lit pas comme les autres. Le chemin est toujours le même pour tout le monde. C'est le nom d'hôte appelé qui désigne la marque. Le serveur lit l'en-tête Host de votre requête, cherche la marque qui a déclaré ce nom de domaine en mode délégué, et sert le document de cette marque.

Le même point d'entrée répond aussi sous le préfixe /v1, à https://id.exemple-sas.example/v1/.well-known/did.json. Les deux adresses appellent le même code. Aucun résolveur did:web n'utilise cette seconde forme : la spécification impose le chemin /.well-known/did.json à la racine du domaine. Appelez la forme sans préfixe.

#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. C'est ce qui permet à un vérificateur tiers de contrôler la signature d'un passeport avec une bibliothèque did:web standard, sans compte chez nous.

#Plafond d'appels

600 appels par fenêtre de 60 secondes, comptés par adresse réseau appelante. Ce compteur est propre à ce document. Le préfixe /v1 ne crée pas un second budget : /.well-known/did.json et /v1/.well-known/did.json partagent le même compteur.

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

#Paramètres de chemin et de requête

Ce point d'entrée n'a aucun paramètre de chemin et aucun paramètre de requête. Le chemin est fixe et identique pour toutes les marques.

#En-têtes

Nom	Type	Obligatoire	Description
`Host`	`string`	oui	Le nom d'hôte qui désigne la marque. C'est le seul élément de la requête que le serveur lit pour choisir la réponse. Votre client HTTP le remplit automatiquement à partir de l'adresse que vous appelez.

Le serveur ramène ce nom d'hôte en minuscules et en retire le numéro de port avant de chercher la marque. ID.Exemple-SAS.example et id.exemple-sas.example:443 désignent donc la même marque.

Aucun autre 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 fictive Exemple SAS, publié sur son domaine délégué id.exemple-sas.example.

curl -i https://id.exemple-sas.example/.well-known/did.json

const reponse = await fetch(
  "https://id.exemple-sas.example/.well-known/did.json",
);

if (reponse.status === 404) {
  console.log("Aucune marque n'est publiée sous ce nom de domaine.");
} else if (reponse.ok) {
  const document = await reponse.json();
  console.log(document.id);
  for (const methode of document.verificationMethod) {
    console.log(methode.id, methode.publicKeyJwk.crv);
  }
  console.log(document.assertionMethod);
} else {
  console.log(reponse.status, await reponse.json());
}

import requests

response = requests.get(
    "https://id.exemple-sas.example/.well-known/did.json",
    timeout=30,
)

if response.status_code == 404:
    print("Aucune marque n'est publiée sous ce nom de domaine.")
elif response.ok:
    document = response.json()
    print(document["id"])
    for methode in document["verificationMethod"]:
        print(methode["id"], methode["publicKeyJwk"]["crv"])
    print(document["assertionMethod"])
else:
    print(response.status_code, response.json())

#Réponse d'exemple

Code HTTP 200OK

Code HTTP 200. Une marque qui a fait tourner sa clef une fois publie deux méthodes de vérification, l'ancienne et la nouvelle.

JSON

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

La réponse compte cinq champs et rien d'autre.

Champ	Type	Description
`@context`	`string[]`	Les deux vocabulaires qui donnent leur sens aux autres champs. Toujours `https://www.w3.org/ns/did/v1` puis `https://w3id.org/security/suites/jws-2020/v1`, dans cet ordre.
`id`	`string`	L'identifiant décentralisé de la marque, de la forme `did:web:` suivi du nom de domaine appelé. C'est la valeur que porte le champ `issuer` des passeports signés par cette marque.
`verificationMethod`	`object[]`	La liste des clefs publiques de la marque. Une entrée par clef. Voir le tableau ci-dessous.
`assertionMethod`	`string[]`	Les identifiants des clefs autorisées à signer un passeport, dans le même ordre que `verificationMethod`.
`authentication`	`string[]`	La même liste d'identifiants que `assertionMethod`.

Chaque entrée de verificationMethod porte quatre champs.

Champ	Type	Description
`id`	`string`	L'identifiant de la clef, de la forme `<identifiant de la marque>#key-<numéro de version>`. C'est la valeur que porte l'en-tête `kid` d'un passeport signé, et c'est elle qui vous dit quelle clef employer.
`type`	`string`	Toujours `JsonWebKey2020`.
`controller`	`string`	L'identifiant décentralisé de la marque. Même valeur que le champ `id` du document.
`publicKeyJwk`	`object`	La clef publique au format JSON Web Key. Une clef sur courbe elliptique NIST P-256 : `kty` vaut `EC`, `crv` vaut `P-256`, `x` et `y` sont les deux coordonnées du point public, encodées en base64url.

La réponse porte aussi ces en-têtes.

En-tête	Contenu
`Content-Type`	`application/json`.
`Cache-Control`	`public, max-age=3600, stale-while-revalidate=86400`. Le document change rarement : un cache peut le garder une heure.
`X-Request-Id`	L'identifiant de votre appel chez nous. Donnez cette valeur au support quand vous signalez une réponse inattendue.
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`	Votre budget d'appels, voir la section Plafond d'appels.

#Ce que contient la liste des clefs

Les clefs sont rendues de la plus ancienne version à la plus récente, par numéro de version croissant.

Une clef retirée du service reste dans le document tant qu'elle n'a pas été révoquée. C'est voulu : un passeport signé sous une ancienne version continue de se vérifier après une rotation. Prenez la clef dont l'identifiant correspond à l'en-tête kid du passeport que vous vérifiez, jamais la dernière de la liste.

Une clef révoquée disparaît du document. Les signatures produites avec elle cessent alors de se vérifier, et c'est le résultat attendu.

Une marque qui n'a encore aucune clef reçoit un document valide dont verificationMethod, assertionMethod et authentication sont des listes vides. Prévoyez ce cas dans votre code.

#Faire pointer votre domaine

Trois façons d'héberger le document existent, et une seule passe par cette adresse chez nous.

Mode	Où vit le document	Adresse résolue
Plateforme	chez nous, sous notre nom de domaine	`https://api.sealtrust.io/brand/{brand_id}/did.json`
Auto-hébergé	chez vous, vous servez le fichier vous-même	`https://votre-domaine/.well-known/did.json`
Délégué	chez nous, sous votre nom de domaine	`https://votre-domaine/.well-known/did.json`

Le mode plateforme est celui appliqué par défaut. Le mode délégué est celui que cette page décrit. Le mode appliqué à votre marque est posé par SealTrust. Écrivez à contact@sealtrust.io pour en changer.

#Erreurs

Le corps d'une réponse d'erreur porte un champ detail, sauf pour le 400 décrit ci-dessous. Toute réponse porte un en-tête X-Request-Id, l'identifiant de votre appel chez nous.

Code	Condition	Que faire
400	Le nom de domaine appelé n'est pas déclaré chez nous. La réponse est du texte brut, `Invalid host header`, sans champ `detail`. Une requête sans en-tête `Host`, ou avec un en-tête `Host` vide, reçoit le même 400.	Contactez le support pour faire déclarer votre domaine délégué avant de mettre l'identité en service.
404	Aucune marque n'a déclaré ce nom de domaine comme son domaine d'identité en mode délégué. `detail` vaut `No DID Document for this host`.	Vérifiez le nom de domaine appelé. Une marque en mode plateforme ou en mode auto-hébergé ne répond jamais ici, même si son domaine pointe vers nous.
404	L'appel arrive sur le nom de domaine vérifié d'une marque, et l'identifiant décentralisé appartient à une autre marque. `detail` vaut `No DID Document for this host`.	Appelez cette adresse sur le domaine de la marque concernée, ou sur `api.sealtrust.io`. Le message est le même que pour un identifiant inconnu, pour ne pas confirmer qu'il existe.
422	Le document d'identité de la marque trouvée ne peut pas être construit. `detail` porte le motif du refus.	Signalez-le au support en indiquant le nom de domaine appelé. Vous ne pouvez rien corriger de votre côté.
429	Plus de 600 appels en 60 secondes depuis votre adresse réseau. `detail` vaut `Rate limit exceeded: 600 requests per 60s`. La réponse porte l'en-tête `Retry-After`, en secondes.	Attendez le nombre de secondes indiqué par `Retry-After`, puis réessayez. Gardez le document en cache de votre côté : il change rarement.
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`.

#Voir aussi

GET /brand/{brand_id}/did.json, récupérer les clefs publiques de signature d'une marque.
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/.well-known/did.json