VerySafe Nous contacter

Développeurs

Deux points d’accès jusqu’au verdict

Lancez une vérification, affichez le lien, lisez le verdict. Requêtes signées, réponses chiffrées, listes de confiance et révocation : tout se passe dans le service.

Langage de l’exemple
curl -X POST "$VERYSAFE_HOST/v1/verifications" \
  -H "Authorization: Bearer $VERYSAFE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "credentialType": "eu_pid",
        "claims": ["age_equal_or_over.18"],
        "flow": "cross_device" }'
const res = await fetch(process.env.VERYSAFE_HOST + "/v1/verifications", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.VERYSAFE_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    credentialType: "eu_pid",
    claims: ["age_equal_or_over.18"],
    flow: "cross_device",
  }),
});
const check = await res.json();
// show check.authorizationRequestUri as a QR code
import os, requests

check = requests.post(
    os.environ["VERYSAFE_HOST"] + "/v1/verifications",
    headers={"Authorization": "Bearer " + os.environ["VERYSAFE_KEY"]},
    json={
        "credentialType": "eu_pid",
        "claims": ["age_equal_or_over.18"],
        "flow": "cross_device",
    },
).json()
# show check["authorizationRequestUri"] as a QR code

201 Created

{ "id": "0f6c1a2e…",
  "status": "pending",
  "flow": "cross_device",
  "credentialType": "eu_pid",
  "requestedClaims": ["age_equal_or_over.18"],
  "authorizationRequestUri": "openid4vp://?client_id=…",
  "pollUrl": "/v1/verifications/0f6c1a2e…" }

Puis, une fois que la personne a répondu · GET /v1/verifications/{id} · 200 OK

{ "id": "0f6c1a2e…",
  "status": "verified",
  "result": {
    "claims": { "age_equal_or_over": { "18": true } } } }

Démarrage rapide

  1. Obtenez une clé

    Les clés sandbox sont gratuites et couvrent toute l’API.

  2. Lancez une vérification

    Envoyez en POST les attributs nécessaires et le parcours (flow). Vous recevez un lien, un QR code ou une demande navigateur.

  3. Lisez le verdict

    Interrogez la vérification ou recevez le webhook signé. Vérifié, avec ce qui a été partagé, ou la raison du refus.

Le déroulé d’une vérification

Qui parle à qui, de la demande au verdict.

  1. Votre application → VerySafeLancer une vérification POST /v1/verifications
  2. VerySafe → Votre applicationUn lien, un QR code ou une demande navigateur 201 Created
  3. Votre application → Portefeuille de la personneLa personne l’ouvre dans son portefeuille
  4. Portefeuille de la personne → VerySafeRécupère la demande signée request.jwt
  5. Portefeuille de la personne → VerySafeEnvoie la réponse chiffrée, une fois que la personne accepte
  6. VerySafeVérifie l’émetteur dans les listes de confiance européennes (les listes de test de l’UE sur la sandbox), la révocation, l’expiration et le lien avec cette demande
  7. VerySafe → Votre applicationLe verdict, avec ce que la personne a partagé GET /v1/verifications/{id} · webhook

Sur le même téléphone, le portefeuille renvoie ensuite la personne vers votre returnUrl, et votre serveur libère le résultat avec POST /v1/verifications/{id}/exchange.

Trois parcours, une API

Un point d’accès, un paramètre : flow. Votre application choisit à chaque vérification.

  • flow: "cross_device"

    Un QR code sur un ordinateur

    Affichez authorizationRequestUri en QR code. La personne le scanne avec le portefeuille de son téléphone ; vous interrogez la vérification ou recevez le webhook.

  • flow: "same_device"

    Un lien sur le même téléphone

    Ouvrez authorizationRequestUri comme lien et envoyez une returnUrl. Le portefeuille y ramène la personne avec un response_code, que votre serveur échange contre le résultat.

  • flow: "dc_api"

    Le navigateur demande directement

    Votre page transmet dcApiRequests à la Digital Credentials API du navigateur et relaie la réponse à dcApiResponseUrl, dans Chrome sur Android et Safari sur iPhone. @verysafe/verify s’en charge pour vous, avec repli sur un lien ou un QR code.

L’API en un coup d’œil

Huit points d’accès que votre application appelle. Le côté portefeuille de l’échange passe par ses propres points d’accès.

  • GET/v1/credential-typesCe que chaque attestation peut divulguer
  • POST/v1/verificationsLancer une vérification et obtenir un lien portefeuille
  • GET/v1/verifications/{id}Statut et résultat : pending, awaiting_return, verified, failed ou expired
  • POST/v1/verifications/{id}/exchangeMême téléphone : libérer le résultat avec le code de réponse de la personne
  • GET/v1/verdictsVotre historique de verdicts pour les audits, sans valeurs personnelles
  • GET/v1/metricsCompteurs et état de chaque liste de confiance européenne
  • GET/v1/webhook-deliveriesLes envois de webhooks signés, et en renvoyer un
  • POST/v1/mcpLes mêmes vérifications, en outils pour agents IA

Chaque refus a une raison

Chaque refus dit pourquoi, en des termes que vous pouvez afficher ou journaliser.

  • Émetteur absent de la liste de confiance européenne
  • Émetteur retiré ou suspendu
  • Attestation révoquée par son émetteur
  • Certificat de l’émetteur révoqué
  • Attestation expirée
  • Preuve non liée à cette demande
  • Statut de révocation invérifiable : la réponse est donc non

Pour les agents IA

Trois outils : list_supported_credential_types, verify_credential et check_verification. L’agent reçoit le verdict et le nom des informations prouvées, jamais leurs valeurs.

tools/call · check_verification
POST /v1/mcp

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "check_verification",
    "arguments": { "session_id": "0f6c1a2e…" } } }

→ { "session_id": "0f6c1a2e…",
    "verdict": "verified",
    "credential_type": "eu_pid",
    "disclosed_claim_names": ["age_equal_or_over.18"] }

Des webhooks signés

Plutôt que d’interroger : en tant que partenaire, vous nous donnez une URL pour chaque client, et chaque résultat y est envoyé. Sur le même téléphone, après l’échange. Avec une clé de sandbox, interrogez la vérification.

Chaque envoi porte un en-tête Signature : une JWS détachée, ES256, sur le corps exact. La clé est sous /.well-known/jwks.json.

Répondez par un 2xx et le résultat est considéré comme remis, et nous supprimons ses données. Sinon il est renvoyé six fois en neuf heures environ, et peut être renvoyé à la demande pendant 30 jours.

Hébergé, ou sur vos propres serveurs

Le même service tourne en image de conteneur signée, publique sur ghcr.io avec sa nomenclature logicielle (SBOM). La licence, le chart Helm et le guide d’installation viennent de nous.