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.
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 codeimport 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
Obtenez une clé
Les clés sandbox sont gratuites et couvrent toute l’API.
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.
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.
- Votre application → VerySafeLancer une vérification
POST /v1/verifications - VerySafe → Votre applicationUn lien, un QR code ou une demande navigateur
201 Created - Votre application → Portefeuille de la personneLa personne l’ouvre dans son portefeuille
- Portefeuille de la personne → VerySafeRécupère la demande signée
request.jwt - Portefeuille de la personne → VerySafeEnvoie la réponse chiffrée, une fois que la personne accepte
- 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
- 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
authorizationRequestUrien 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
authorizationRequestUricomme lien et envoyez unereturnUrl. Le portefeuille y ramène la personne avec unresponse_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/verifys’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.
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.
Obtenir une clé sandbox
Environnement et attestations de test. Aucune carte bancaire requise. Une personne vous répond avec votre clé.
Ressources
- La référence de l’API, à essayerChaque point d’accès, sur la sandbox, dans votre navigateur. (s’ouvre dans un nouvel onglet)
- Le document OpenAPILa même référence en un seul fichier, pour vos outils. (s’ouvre dans un nouvel onglet)
- La bibliothèque navigateur, @verysafe/verifyD’abord l’invite du navigateur, puis un lien sur le téléphone, puis un QR code. Sur npm. (s’ouvre dans un nouvel onglet)
- Les raisons de refusChaque raison pour laquelle une vérification peut répondre non.
- MCP pour les agents IALes trois outils, et ce qu’ils renvoient.
