Authentification & clés API
Tu crées ton compte en self-service sur /register et tu repars avec deux secrets, affichés une seule fois chacun. Ils ont des rôles opposés — à ne pas confondre.
Deux secrets, deux directions
| Secret | Sert à | Direction |
|---|---|---|
Clé API sp_… |
Authentifier tes appels vers l'API ProofIt. | Toi → ProofIt |
| Secret HMAC de callback | Vérifier la signature des webhooks que ProofIt t'envoie. | ProofIt → toi |
S'authentifier sur /v1
Méthode 1 — clé API directe (recommandée pour démarrer)
Passe ta clé sp_ en bearer + ton organisation en header. Rien à échanger.
curl http://proof.test/v1/sessions \ -H "Authorization: Bearer sp_xxx" \ -H "X-Organisation-Id: 01900000-0001-7000-8000-000000000001"
Le header X-Organisation-Id est obligatoire avec cette méthode : la clé seule ne porte pas l'organisation.
Méthode 2 — JWT court (optionnelle)
Pour éviter de faire circuler la clé longue durée, échange-la contre un JWT HS256 valable 1h. Le JWT porte l'organisation dans son claim aud — X-Organisation-Id devient inutile.
# Échange curl -X POST http://proof.test/oauth/token \ -d "grant_type=client_credentials&client_secret=sp_xxx" # Réponse { "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 3600, "scope": "sessions:write sessions:read proofs:read" }
Les SDKs gèrent cet échange et l'auto-refresh pour toi.
Scopes
Un API client porte un sous-ensemble de scopes. À l'inscription, ta première clé reçoit par défaut sessions:write sessions:read proofs:read.
| Scope | Autorise |
|---|---|
sessions:write | Ouvrir / valider / clore des sessions |
sessions:read | Lire l'état d'une session |
actions:write | Enregistrer des actions signées |
artifacts:write / artifacts:read | Attacher / lire des artefacts (PDF, certificats) |
proofs:read | Générer / télécharger les bundles de preuve |
timelines:read | Lire la timeline d'une session |
events:write | Émettre des events métier |
webhooks:write / webhooks:read | Gérer / lire les souscriptions webhook |
checkpoints:read / checkpoints:witness | Lire la tête de chaîne signée / la contre-signer en témoin (couche 4) |
sessions:write ⇒ sessions:read + actions:write ·
artifacts:write ⇒ artifacts:read ·
webhooks:write ⇒ webhooks:read.
Rotation
Tu peux créer plusieurs clés (une par environnement — prod, staging…) depuis ton espace admin, façon DocuSign/Yousign. Le secret n'est montré qu'à la création ; on n'en stocke qu'un hash Argon2id. Révoque une clé compromise sans toucher aux autres.
Affiché une fois à l'inscription. Régénérable depuis l'admin (action « Régénérer le secret de callback », réservée au propriétaire de l'organisation). Les anciens secrets cessent immédiatement de fonctionner — mets à jour ton serveur avant de régénérer.