2. Se connecter (TOTP)

L'entreprise se connecte par e-mail et mot de passe. Le TOTP (Google Authenticator, Authy…) est obligatoire : aucun jeton complet n'est jamais renvoyé directement, la réponse indique l'étape suivante.

Se connecter

POST/auth/loginPublic

Corps de la requête

{
  "email": "[email protected]",
  "password": "<mot-de-passe>"
}

Cas 1 : TOTP pas encore configuré (première connexion)

{
  "success": true,
  "data": {
    "requires_totp_setup": true,
    "setup_token": "..."
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Cas 2 : TOTP déjà configuré

{
  "success": true,
  "data": {
    "requires_totp": true,
    "challenge_token": "550e8400-e29b-41d4-a716-446655440000"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	Quand
422	Identifiants incorrects, compte désactivé, ou compte particulier (utiliser la connexion par téléphone).

Mot de passe oublié : POST /auth/password/forgot puis POST /auth/password/reset.

Première connexion : activer le TOTP

POST/auth/totp/setupsetup_token (Bearer)

Avec Authorization: Bearer {setup_token} (valable 15 min). Renvoie le secret à scanner dans Google Authenticator ou Authy.

Réponse 200

{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_url": "otpauth://totp/KratosPay:...",
    "manual_entry_key": "JBSWY3DPEHPK3PXP"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	Quand
401	`setup_token` expiré : se reconnecter.

Confirmer le TOTP et recevoir le jeton

POST/auth/totp/confirmsetup_token (Bearer)

Saisissez le premier code à 6 chiffres généré par l'application. La configuration expire après 10 minutes.

Corps de la requête

{
  "code": "123456"
}

Réponse 200

{
  "success": true,
  "data": {
    "merchant": {
      "...": "..."
    },
    "token": "<jeton-de-session>",
    "token_type": "Bearer",
    "recovery_codes": [
      "XXXX-XXXX-XXXX",
      "... 10 codes au total"
    ]
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	Quand
422	Code invalide ou session expirée.

Conservez les 10 codes de récupération en lieu sûr : ils ne seront plus jamais affichés. Chacun remplace un code TOTP, à usage unique.

Connexions suivantes : répondre au défi TOTP

POST/auth/totp/challengePublic

À utiliser après une connexion qui a renvoyé requires_totp. Le challenge_token est à usage unique, valable 5 minutes.

Corps de la requête

{
  "challenge_token": "550e8400-e29b-41d4-a716-446655440000",
  "code": "123456"
}

Réponse 200

{
  "success": true,
  "data": {
    "requires_totp": false,
    "merchant": {
      "...": "..."
    },
    "token": "<jeton-de-session>",
    "token_type": "Bearer"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	Quand
422	Code invalide, challenge expiré ou déjà consommé (un code de récupération `XXXX-XXXX-XXXX` est aussi accepté).