Référence technique

Le détail contractuel des quatre endpoints que votre application appelle directement : codes de réponse, cas d'erreur, limites de débit. Pour le schéma exact, interrogeable et à jour en continu, la documentation Swagger est disponible sur todis.eu/docs, sans jeton requis.

Authentification et limites de débit

Toutes les routes de vérification exigent l'en-tête Authorization: Bearer <jeton>. Un jeton manquant, invalide, révoqué ou expiré renvoie 401. Au-delà de la limite de votre plan (30 requêtes/seconde en Starter, 60 en Standard), une requête renvoie 429.

Qui décide quelles informations sont divulguées

Chaque attribut d'une présentation SD-JWT VC (l'âge, un diplôme, un statut) est protégé par son propre digest salé dans le JWT signé. Le portefeuille ne joint à sa présentation que la valeur et le sel des attributs que l'utilisateur a accepté de révéler : les autres restent des empreintes non réversibles. Todis n'a techniquement accès qu'à ce qui est effectivement divulgué dans la présentation qu'il reçoit, jamais plus.

Avec POST /verify/sessions, le champ claims de votre requête devient une requête DCQL intégrée à la demande d'autorisation envoyée au portefeuille : l'utilisateur voit et approuve exactement cette liste avant que son portefeuille ne construise la présentation. Avec POST /verify/sd-jwt-vc, cette étape a déjà eu lieu avant que vous n'obteniez la présentation : Todis la vérifie et vous renvoie son contenu tel quel.

POST /verify/sd-jwt-vc

Vérifie une présentation SD-JWT VC. Deux modes au choix dans le corps de la requête : issuer_public_key_pem (clé de l'émetteur fournie directement) ou country_code (résolution automatique via le registre officiel de l'UE) ; issuer_public_key_pem est prioritaire si les deux sont présents.

  • 200 : présentation vérifiée, claims renseigné.
  • 400 : ni issuer_public_key_pem ni country_code fourni.
  • 401 : jeton de licence manquant, invalide, révoqué ou expiré.
  • 422 : présentation malformée ou signature non vérifiée (verified: false, détail dans error).
  • 429 : quota de requêtes du plan dépassé.
  • 502 : résolution du registre de confiance de l'émetteur impossible (mode country_code uniquement, ex. registre européen temporairement indisponible).

POST /verify/mdoc

Vérifie une présentation mdoc (ISO/IEC 18013-5, notamment permis de conduire mobile). Le certificat de confiance de l'émetteur (issuer_trust_anchor_pem) doit être fourni explicitement dans le corps de la requête : il n'y a pas encore de résolution automatique par pays pour ce format (contactez-nous si un émetteur mdoc particulier vous concerne).

  • 200 : présentation vérifiée, doc_type et namespaces renseignés.
  • 401 : jeton de licence manquant, invalide, révoqué ou expiré.
  • 422 : présentation malformée, certificat de confiance incorrect, ou signature non vérifiée.
  • 429 : quota de requêtes du plan dépassé.

POST /verify/sessions

Crée une session de vérification OpenID4VP. Le corps de la requête liste le type de credential demandé (vct) et les attributs demandés (claims, chemins simples, ex. "age_over_18"), avec le même choix issuer_public_key_pem/country_code que pour la vérification directe. La réponse contient une requête d'autorisation OpenID4VP à présenter au portefeuille de l'utilisateur (QR code ou lien profond). La session expire 15 minutes après sa création, qu'elle ait reçu une réponse ou non. 

curl -X POST https://verify.todis.eu/verify/sessions \
  -H "Authorization: Bearer VOTRE_JETON" \
  -H "Content-Type: application/json" \
  -d '{
    "vct": "https://example.eu/credentials/pid",
    "claims": ["age_over_18"],
    "country_code": "FR"
  }'
  • 201 : session créée, avec session_id et authorization_request.
  • 400 : claims vide, ou ni issuer_public_key_pem ni country_code fourni.
  • 401 : jeton de licence manquant, invalide, révoqué ou expiré.
  • 429 : quota de requêtes du plan dépassé.

GET /verify/sessions/{id}

Consulte le résultat d'une session créée par POST /verify/sessions, à interroger après que l'utilisateur a répondu avec son portefeuille (ou périodiquement en attendant). 

curl https://verify.todis.eu/verify/sessions/<session_id> \
  -H "Authorization: Bearer VOTRE_JETON"
  • 200 : trois statuts possibles, {"status": "pending"}, {"status": "verified", "claims": {...}} ou {"status": "failed", "error": "..."}.
  • 401 : jeton de licence manquant, invalide, révoqué ou expiré.
  • 404 : session inconnue (identifiant invalide, ou session expirée après 15 minutes).
  • 429 : quota de requêtes du plan dépassé.

Format de réponse (vérification directe)

Pour /verify/sd-jwt-vc et /verify/mdoc : un champ verified (booléen) et, selon le résultat, soit les informations divulguées (claims pour SD-JWT VC, doc_type/namespaces pour mdoc), soit un champ error texte. Jamais l'intégralité du document d'identité, seulement les attributs effectivement divulgués (voir ci-dessus).

Aller plus loin

Pour la vue d'ensemble (authentification, deux façons d'intégrer, exemple curl), voir Comment fonctionne l'API. Pour le schéma exact des requêtes/réponses, todis.eu/docs (Swagger). Une question qui n'est pas couverte ici ? contact@todis.eu.