L'API Idkey : la vérification se fait toute seule.

Documentation · v1

1. Votre clé API

Une clé par établissement ou par logiciel, avec l'adresse de votre webhook. Demandez-la depuis la page d'essai : vous recevez la clé idk_… et le secret du webhook whsec_…. Gardez-les côté serveur, jamais dans une app ou une page web.

curl https://idkey.pro/api/v1/moi \
  -H "Authorization: Bearer idk_VOTRE_CLE"

2. Créer une demande

Votre serveur génère une paire de clés ECDH P-256 (une par demande, ou une pour votre serveur) et envoie la clé publique. Idkey renvoie le lien à transmettre au client : par e-mail, SMS, dans votre app ou en QR code.

curl -X POST https://idkey.pro/api/v1/demande \
  -H "Authorization: Bearer idk_VOTRE_CLE" \
  -H "content-type: application/json" \
  -d '{
    "pub": "BASE64URL_CLE_PUBLIQUE_P256",
    "champs": ["nom", "naissance", "adresse"],
    "motif": "Location du 12 au 15 mars",
    "ref": "RESA-48213",
    "duree": 86400
  }'

{ "ok": true, "code": "K7P2M9QX",
  "lien": "https://idkey.fr/d/K7P2M9QX#BASE64URL_CLE_PUBLIQUE_P256",
  "expire": "2026-03-11T10:00:00.000Z", "ref": "RESA-48213" }

3. Le webhook

Dès que la personne valide avec Face ID, Idkey envoie un POST à votre webhook. Le contenu reste chiffré pour votre clé.

POST https://votre-logiciel.fr/idkey
x-idkey-signature: t=1767225600,v1=5f2c…

{ "event": "demande.repondue", "code": "K7P2M9QX", "ref": "RESA-48213",
  "date": "2026-03-10T10:02:11.000Z", "epk": "…", "box": "…" }

Vérifiez la signature : HMAC-SHA256 de t + "." + corps brut avec votre secret whsec_…, et refusez un t de plus de 5 minutes. Pas de webhook ? Interrogez GET /api/v1/demande/CODE/reponse : la réponse n'est remise qu'une fois, puis effacée.

4. Déchiffrer et vérifier (Node.js 18+)

import { webcrypto as c } from "node:crypto";
const s = c.subtle, ub64 = (t) => Buffer.from(t, "base64url");

// À la création : une paire de clés, la publique part dans "pub"
const kp = await s.generateKey({ name: "ECDH", namedCurve: "P-256" }, true, ["deriveBits"]);
const pub = Buffer.from(await s.exportKey("raw", kp.publicKey)).toString("base64url");

// À la réception du webhook
async function ouvrir({ epk, box }) {
  const them = await s.importKey("raw", ub64(epk), { name: "ECDH", namedCurve: "P-256" }, false, []);
  const bits = await s.deriveBits({ name: "ECDH", public: them }, kp.privateKey, 256);
  const hk = await s.importKey("raw", bits, "HKDF", false, ["deriveKey"]);
  const key = await s.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(0),
    info: new TextEncoder().encode("idkey-demande") }, hk, { name: "AES-GCM", length: 256 }, false, ["decrypt"]);
  const all = Buffer.from(box, "base64");
  const r = JSON.parse(new TextDecoder().decode(
    await s.decrypt({ name: "AES-GCM", iv: all.subarray(0, 12) }, key, all.subarray(12))));
  // Signature de la clé d'accès du client (Face ID)
  const k = await s.importKey("raw", ub64(r.pub), { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
  const ok = await s.verify({ name: "ECDSA", hash: "SHA-256" }, k, ub64(r.sig), new TextEncoder().encode(r.p));
  return { signatureValide: ok, ...JSON.parse(r.p) };
}

Le contenu signé p donne f (les champs acceptés par la personne), niveau (authentifiee : puce de la pièce lue, controlee : pièce et selfie contrôlés, declaree), pour et signe (date). Conservez la réponse dans votre dossier : elle reste vérifiable.

5. Vérifier un PDF Idkey

Un client vous envoie un PDF scellé ? Calculez son SHA-256 et demandez à Idkey s'il est intact.

curl https://idkey.pro/api/v1/sceau/h/SHA256_DU_FICHIER

Limites et engagements

• Aucune image de pièce d'identité ne transite par l'API
• Réponses chiffrées pour votre clé, effacées chez Idkey après remise
• Clé révocable à tout moment
• Hébergement européen, journal des demandes par clé

Demander une clé API