Démarrage rapide
De zéro à un dossier de preuve ASiC-E téléchargé, en 5 minutes et 5 commandes curl.
Créer son compte (self-service)
Rends-toi sur /register : tu crées ton organisation et tu repars avec deux secrets affichés une seule fois :
- ta clé API (préfixe
sp_), avec les scopessessions:writesessions:readproofs:readpar défaut ; - ton secret HMAC de callback, pour vérifier la signature des webhooks.
Note ton organisation_id (UUID) affiché dans ton espace admin. Vérifie le solde de crédits (voir Crédits) — une session coûte 1 crédit, un bundle 5.
S'authentifier
Le plus simple : utilise ta clé sp_ directement comme bearer, en précisant ton organisation via le header X-Organisation-Id. Pas d'échange de token à faire.
# Sur chaque appel /v1 :
-H "Authorization: Bearer sp_xxx" \
-H "X-Organisation-Id: 01900000-0001-7000-8000-000000000001"
POST /oauth/token (grant_type=client_credentials&client_secret=sp_xxx). Le JWT porte l'organisation dans son claim aud — le header X-Organisation-Id devient alors inutile. Les SDKs gèrent cet échange automatiquement.
Ouvrir une session
Mode minimal SMS. Tu reçois un session_id ; l'utilisateur reçoit un OTP par SMS.
curl -X POST http://proof.test/v1/sessions \
-H "Authorization: Bearer sp_xxx" \
-H "X-Organisation-Id: 01900000-..." \
-H "Content-Type: application/json" \
-d '{
"channel": "sms",
"actor_user_id": "user-001",
"phone_number": "+33600000001"
}'
# Réponse
{ "session_id": "01900000-...", "state": "PENDING_OTP", "expires_at": "..." }
💡 Pour aller plus loin : ajoute planned_operations pour sceller la liste prévisionnelle — voir Manifest prévisionnel.
Valider l'OTP
L'utilisateur a reçu le code. En dev avec APP_OTP_FIXED=true c'est 000000.
curl -X POST http://proof.test/v1/sessions/01900000-.../validate \
-H "Authorization: Bearer sp_xxx" \
-H "X-Organisation-Id: 01900000-..." \
-d '{"otp": "000000"}'
# Une entrée LOGIN est ancrée + mail témoin DKIM part
Enregistrer une action signée
Chaque action est append à la chaîne, co-signée Ed25519 par organisation + master.
curl -X POST http://proof.test/v1/sessions/01900000-.../actions \
-H "Authorization: Bearer sp_xxx" \
-H "X-Organisation-Id: 01900000-..." \
-d '{
"event_type": "VALIDATION_ACTION",
"payload_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"metadata": {"document_id": "doc-42", "action": "signature"}
}'
Clore la session + télécharger le bundle
Le close calcule session_root_hash, envoie le mail récap au bénéficiaire, déclenche l'ancrage immédiat de la session, et libère le bundle.
Ajoutez "require_anchored": true au corps de POST /v1/proofs pour n'obtenir que la preuve finale ancrée (422 ANCHORS_PENDING sinon) — sans le flag, un bundle provisoire est déclaré tel dans son manifest et refusé par les vérificateurs. En pratique : attendez plutôt le webhook bundle.generated (anchor_coverage: complete). Et sur toute route mutante, le header Idempotency-Key rend vos retries sûrs (réponse rejouée, jamais de doublon).
# 5a. Close curl -X POST http://proof.test/v1/sessions/01900000-.../close \ -H "Authorization: Bearer sp_xxx" \ -H "X-Organisation-Id: 01900000-..." # 5b. Download proof bundle (ASiC-E ZIP) curl -X POST http://proof.test/v1/proofs \ -H "Authorization: Bearer sp_xxx" \ -H "X-Organisation-Id: 01900000-..." \ -d '{"session_id": "01900000-..."}' \ -o bundle.asice # Le ZIP contient : manifest signé, entrées audit JSON, EML des mails, # ancrages OTS+RFC 3161, canary, README/TIMELINE/VERIFICATION lisibles.
Refuser une session
Si l'utilisateur clique "Refuser" ou si tu détectes une fraude côté SI, marque la session comme ABANDONED + entrée REFUSED ancrée dans la chaîne.
curl -X POST http://proof.test/v1/sessions/01900000-.../refuse \
-H "Authorization: Bearer sp_xxx" \
-H "X-Organisation-Id: 01900000-..." \
-d '{"reason":"user_explicit"}'
# Tu peux quand même générer un bundle ASiC-E ensuite —
# il prouvera le REFUS avec son entrée co-signée.