GETMéthode GET/passport/{identifier}/vc/verify

Vous faites contrôler la signature du passeport numérique d'un produit, et vous récupérez les données que cette signature couvre. En quittant cette page, vous saurez demander ce contrôle depuis n'importe quel identifiant de produit, distinguer un contrôle qui échoue d'une requête qui échoue, et savoir quelles données la réponse vous montre selon le niveau d'accès que vous demandez.

Adresse complète :

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

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

Le passeport est délivré au format SD-JWT-VC, une attestation signée dont chaque champ peut être révélé ou retenu séparément. L'émetteur est la marque, identifiée par un identifiant décentralisé did:web. Ce point d'entrée recompose l'attestation au niveau d'accès que vous demandez, contrôle sa signature, et vous rend les données révélées.

#Autorisation

Aucun droit de clef d'API n'est vérifié sur ce point d'entrée. Deux contrôles s'appliquent malgré tout : l'origine de votre appel, puis le niveau d'accès que vous demandez.

#D'où vous appelez

Appelez ce point d'entrée depuis votre serveur.

Nous refusons en 403 tout appel qui porte un en-tête Origin ou Referer désignant un domaine autre que les nôtres. Le champ detail vaut alors Forbidden origin. Un navigateur pose toujours l'un de ces deux en-têtes, donc une page web hébergée ailleurs que chez nous ne peut pas appeler cette adresse depuis le navigateur de son visiteur.

Le cookie de session ne fonctionne que depuis une page servie par un de nos domaines. Nous refusons en 403 un appel qui porte ce cookie sans en-tête Origin ni Referer, avec detail à Origin or Referer header required. Depuis un serveur, présentez donc le jeton de session dans l'en-tête Authorization: Bearer.

#Le niveau que vous demandez

Les niveaux public et end_user ne demandent aucun compte. Les cinq autres valeurs du paramètre access_tier exigent une session de compte, présentée par l'en-tête Authorization: Bearer <jeton de session> ou par le cookie de session posé à la connexion.

Une session ayant accès à la marque du produit ouvre les trois niveaux de métier sur ses propres produits. Le rôle d'autorité de surveillance du marché les ouvre également, sur tous les produits.

Une clef d'API partenaire n'ouvre rien ici. Le jeton reçu dans l'en-tête Authorization est décodé comme un jeton de session de compte utilisateur, et une clef d'API n'en est pas un. La lecture échoue en silence et l'appel se poursuit comme un appel anonyme.

#Plafond d'appels

60 appels par tranche de 60 secondes, comptés par adresse IP appelante. La fenêtre est fixe.

Ce plafond est partagé par toutes les adresses qui commencent par /passport. Les formes /passport/… et /v1/passport/… alimentent le même compteur, le préfixe /v1 ne crée pas un second budget.

Chaque réponse acceptée porte trois en-têtes qui décrivent ce compteur.

Un dépassement renvoie 429, avec les mêmes trois en-têtes et un Retry-After. Sur ce point d'entrée, Retry-After vaut la durée de la fenêtre, soit 60 secondes.

#Paramètres de chemin et de requête

#Les trois formes d'identifiant acceptées

L'empreinte d'identifiant existe pour un produit en QR seul comme pour un produit à puce NFC. Le serveur la tire au hasard pour un produit en QR seul. Il la dérive de l'identifiant de la puce pour un produit à puce NFC. Les deux formes ont donc la même allure et se demandent de la même manière.

Nous reconnaissons la forme à l'écriture. Une valeur qui commence par 0x et fait exactement 66 caractères, nous la cherchons comme une empreinte d'identifiant. Toute autre valeur, nous la cherchons d'abord comme un identifiant de jeton, puis comme un numéro de série quand la première recherche n'a rien donné.

Vous écrivez l'empreinte d'identifiant dans la casse que vous voulez. Vous écrivez le numéro de série dans la casse que vous voulez également, et nous le canonicalisons comme le fait le résolveur du QR : nous y lisons les lettres I et L comme un 1, la lettre O comme un 0. Vous pouvez donc recopier à la main un numéro lu sur une étiquette.

Le numéro de certificat d'authenticité n'est pas accepté ici.

Un produit détruit sur la chaîne ou retiré du catalogue ne se résout plus par ce point d'entrée, et la réponse est alors 404.

#Les six valeurs de access_tier

Ces niveaux sont des publics différents, sans hiérarchie entre eux. Chacun des trois niveaux de métier hérite du niveau public et du niveau utilisateur final, puis ajoute ce que son métier demande.

Une marque peut remplacer ces règles par les siennes. Le tableau ci-dessus décrit ce qui s'applique à défaut de règles propres à la marque.

#En-têtes

Aucun en-tête n'est requis pour les niveaux public et end_user. Les cinq autres niveaux exigent l'en-tête Authorization ou le cookie de session. Dans tous les cas, respectez la règle d'origine décrite plus haut.

#Corps de la requête

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