Sachez qui est votre client, sans conserver sa pièce d’identité

1. Obtenez un client

Nous enregistrons votre client — un identifiant client et un secret, affiché une seule fois — un plan (niveau, attestations et la finalité que la personne lira) et vos URI de redirection : une page https, le schéma propre à votre application (yourapp://verify), ou les deux. Chaque client dispose d’un environnement de test dédié avant la mise en production.

2. Envoyez la demande depuis votre backend

Jamais depuis un navigateur ou une application : le secret reste sur votre serveur. Vous obtenez un lien à usage unique, valable dix minutes ; une fois ouvert, la personne dispose d’une heure pour terminer.

POST https://api.ism.ec/verify/v1/par
{
  "client_id":     "cl_…",
  "client_secret": "…",
  "plan_id":       "bn_…",
  "redirect_uri":  "yourapp://verify",
  "state":         "<aléatoire, conservé dans votre session>"
}

→ { "req": "…", "verify_url": "https://id.ism.ec/go?req=…", "expires_at": "…" }

3. La personne se vérifie

Ouvrez le lien sur son téléphone, affichez-le sous forme de QR code sur un ordinateur, ou envoyez-le par le canal que vous utilisez déjà avec votre client. Le lien ne contient qu’une référence opaque — ni client, ni périmètre, ni donnée personnelle.

4. Retour chez vous

Une fois la vérification terminée, ID Protekt ouvre votre redirect_uri avec ?code=…&state=…. Vérifiez que state est bien celui que vous avez conservé.

5. Récupérez la réponse

Échangez le code sans attendre : il est à usage unique, vit 120 secondes, et seul le client pour lequel il a été émis peut l’utiliser. Les identifiants vont dans le corps de la requête ou en HTTP Basic.

POST https://api.ism.ec/verify/v1/token
{ "client_id": "cl_…", "client_secret": "…", "code": "<issu de la redirection>" }

→ {
    "claims":             { "subject_is": true },
    "assurance":          "L4",
    "verified_by":        "device",
    "device_attestation": "…",
    "verified_at":        "…",
    "consent_receipt_id": "…",
    "state":              "…"
  }

La personne n’est pas revenue ? Vous recevez quand même la réponse

Enregistrez un webhook et votre backend est informé de chaque issue — terminée, refusée ou échouée — même si la personne termine dans l’application ID Protekt sans jamais revenir, ou a commencé sur un ordinateur. Chaque événement est signé avec votre propre secret whsec_ (ISM-Signature, HMAC-SHA256), contient la référence de la demande et aucune donnée personnelle, et est renvoyé pendant environ une journée. Récupérez ensuite le résultat par sa référence, dans les 24 heures :

POST https://api.ism.ec/verify/v1/token
{
  "client_id":     "cl_…",
  "client_secret": "…",
  "grant_type":    "request",
  "req":           "<issu du webhook>"
}

La réponse n’est délivrée qu’une fois, par le code ou par la référence, selon ce qui arrive en premier.

Lisez l’attestation, pas le statut. Une vérification terminée n’est pas une validation : subject_is: false est un refus, et une attestation absente n’a pas été prouvée. Gardez la session de la personne ouverte : si elle ne revient pas, elle peut simplement réessayer.