Cycle de vie

Cette page couvre les opérations courantes sur les credentials et les connexions : rotation, révocation, qui peut faire quoi.

Lifecycle d'une connexion (intégration ↔ marchand)

Rotation du webhook secret

Pourquoi rotater

• Compromission : votre webhook_secret a fuité (commit dans un repo public, ex-employé, etc.). Vous devez forcer Nex à signer avec un nouveau secret pour invalider l'ancien.
• Hygiène périodique : best practice de tourner les secrets sensibles tous les 90 jours (cf. OWASP).
• Réinitialisation legacy : votre intégration a été créée avant la mise en place du stockage chiffré du secret. La rotation est obligatoire pour que Nex puisse re-signer.

Qui peut le faire

V1, seul l'admin Nex peut déclencher la rotation depuis le CMMS. Vous ne pouvez pas vous auto-rotater (spec-08 à venir).

Demande : email à partners@paywithnex.com avec votre integration_id et le motif. SLA 1 jour ouvré.

Procédure

1. Vous préparez votre receiver à accepter le nouveau secret (mais sans encore le déployer).
2. L'admin Nex clique "Rotater" dans le CMMS. Le nouveau secret est affiché 1 fois dans la console.
3. L'admin vous le transmet par canal sécurisé.
4. Vous déployez le nouveau secret sur tous vos workers receivers en même temps (sinon certains nodes rejettent les signatures du nouveau secret, d'autres rejettent les signatures de l'ancien).
5. Vous confirmez à Nex que c'est déployé.

Rotation hard V1

L'ancien secret est invalidé immédiatement côté Nex au moment du clic. Tout webhook en flight signé avec l'ancien secret avant la rotation sera rejeté par votre receiver. C'est attendu — coordonnez le timing avec Nex.

Une variante "soft rotation" (accepter 2 secrets simultanément pendant N jours) est prévue dans une spec future. Pour l'instant, prévoyez une fenêtre de coordination.

Rotation des clés API (nex_sk_live_xxx)

Différent du webhook secret : ici on parle de plusieurs clés actives simultanément (pattern multi-keys).

Pattern multi-keys

Vous pouvez avoir N clés API actives en parallèle sur votre intégration. Chacune authentifie vos appels indépendamment. C'est la solution pour rouler une nouvelle clé sur une partie de votre flotte de terminaux sans casser le reste.

Procédure typique de rotation

1. Demandez à Nex de créer une nouvelle clé (POST /admin/integrations/:id/api-keys côté CMMS).
2. Nex vous transmet la nouvelle clé.
3. Vous déployez la nouvelle clé sur un sous-ensemble de terminaux (canary).
4. Vous validez que le canary fonctionne avec la nouvelle clé.
5. Vous étendez progressivement à tous les terminaux.
6. Une fois 100% migré, demandez à Nex de révoquer l'ancienne clé. Elle devient inutilisable.

À aucun moment vous n'avez de fenêtre où ça casse. Très utile pour les flottes terminaux qui ne sont pas updatables à la demande (terminaux physiques offline pendant des jours).

Toujours garder ≥ 1 clé active

Nex refuse de révoquer la dernière clé active d'une intégration. C'est volontaire — sinon votre intégration devient muette sans recours.

Révoquer une connexion (intégration ↔ marchand)

Une connexion active peut être révoquée par trois acteurs distincts, avec des conséquences identiques (status → revoked, revoked_by enregistré).

Qui révoque	Comment	Quand c'est le bon choix
Le marchand	Bouton "Révoquer" sur son business-dashboard /merchant/integrations	Le marchand a perdu confiance dans votre app, ou ne l'utilise plus.
Vous (partner)	POST /partners-public/connections/:id/revoke avec votre Bearer	Vous arrêtez de servir ce marchand (résiliation contrat, off-boarding).
Nex (admin)	Bouton "Révoquer toute l'intégration" dans CMMS	Vous êtes en faute (compromission massive, fraude). Cascade sur toutes vos connexions.

Conséquences après révocation

• Les QR déjà créés restent valides jusqu'à leur expiresAt (un client peut encore les payer pendant 5 min).
• Nouveaux POST /orders sur ce marchand → 403 NO_ACTIVE_CONNECTION.
• Webhooks pending pour les transactions issues d'avant la révocation continuent à être envoyés (BullMQ retry inchangé).
• Le marchand peut vous re-accorder une nouvelle connexion plus tard via une nouvelle POST /connections/request de votre part.

Désactiver votre intégration entière

Cas extrême : vous arrêtez votre activité, ou Nex décide de suspendre votre partenariat.

Côté Nex (admin) : "Révoquer l'intégration" dans CMMS. Conséquences :

1. Toutes vos clés API sont invalidées immédiatement (auth 401 désormais).
2. Toutes vos connexions actives sont révoquées en cascade (status → revoked).
3. Aucune nouvelle commande ne peut être créée.
4. Les webhooks pending sont toujours envoyés (vous récupérez l'argent dû aux marchands déjà payés).
5. L'historique reste consultable en BD pour audit.

La révocation est irréversible côté API — pour réactiver, il faut créer une nouvelle intégration (nouveau integration_id, nouvelles clés).

Matrice "qui peut faire quoi"

Action	Vous (partner)	Marchand	Nex (admin)
Créer votre intégration	❌	❌	✅
Voir vos clés API (préfixes)	❌ V1 (spec-08)	❌	✅
Créer une nouvelle clé API	❌ V1 (spec-08)	❌	✅
Révoquer une clé API	❌ V1 (spec-08)	❌	✅
Rotater le webhook secret	❌ V1 (spec-08)	❌	✅
Modifier votre webhook URL	❌ V1 (spec-08)	❌	✅
Demander une connexion	✅ POST /connections/request	❌	✅ (au nom du partner)
Accepter une connexion	❌	✅ /merchant/integrations	❌
Refuser une connexion	❌	✅ /merchant/integrations	❌
Révoquer une connexion active	✅ POST /connections/:id/revoke	✅ /merchant/integrations	✅
Révoquer votre intégration entière	❌	❌	✅

Self-serve V2

Toutes les actions marquées "❌ V1 (spec-08)" passeront dans un futur portail self-serve partenaire. En attendant, demande à partners@paywithnex.com.

Voir aussi

• Connecter un marchand — créer une connexion
• Encaisser pour un marchand — utilisation au quotidien
• Référence API — endpoints /connections/*