Account Recovery: 2FA and Transaction PIN

​

Contents

• Before you start
• Two-factor authentication
  • Turn on 2FA and save the recovery codes
  • Generate new recovery codes
  • Reset 2FA with a recovery code
• Transaction PIN
  • Set or change the PIN
  • Verify the PIN
  • Reset a forgotten transaction PIN
• Passkey confirmation
• Limits
• Errors
• Frontend flow
• Security notes

​

Before you start

• Base URLs: sandbox https://smtp.yativo.com, production https://api.yativo.com. All paths below include /api/v1.
• Dashboard only. Every endpoint here needs the signed-in person’s bearer token. They can’t be called with an API key (403 This endpoint cannot be used with an API key. ...).
  Authorization: Bearer <ACCESS_TOKEN>
  
• Each person recovers their own account. For a team member these endpoints act on the member’s own 2FA, PIN and passkeys, never the team owner’s. See Team Functionality.
• A passkey is required for both resets. A user with no passkey can’t reset 2FA or the PIN themselves and gets 403. Encourage users to add a passkey (Passkey Login) when they turn on 2FA.
• Both resets work while business KYC is still pending.
• Responses use the standard envelope: { "status": "success" | "failed", "status_code": ..., "message": "...", "data": { ... } }. See API Responses & Errors.

​

Two-factor authentication

​

Turn on 2FA and save the recovery codes

1. Get a secret and show it to the user as a QR code or text:
   POST /api/v1/generate-2fa-secret
   
   { "status": "success", "status_code": 200, "data": { "secret": "JBSWY3DPEHPK3PXP" } }
   
2. The user adds it to their authenticator app and enters the current 6-digit code:
   POST /api/v1/enable-2fa
   Content-Type: application/json
   
   { "secret": "JBSWY3DPEHPK3PXP", "otp": "123456" }
   
   {
     "status": "success",
     "status_code": 200,
     "message": "Request successful",
     "data": {
       "message": "2FA enabled successfully",
       "recovery_codes": [
         "7KQ2M-X9PTD", "H4W8N-2RCZE", "0MBV6-YQ3KS", "TJ9PA-5DXWR", "8CNE2-VHM4G",
         "Q6ZT1-BWKP7", "R2XJD-9AEN5", "5YHMC-K8TQW", "WPD3G-6ZN0B", "M1AKX-T4RVH"
       ]
     }
   }
   

• are 10 characters, shown as XXXXX-XXXXX;
• work once each;
• ignore case, spaces and the dash; O, I and L are read as 0, 1, 1;
• are deleted when 2FA is turned off or reset.

​

Generate new recovery codes

POST /api/v1/2fa/recovery-codes
Content-Type: application/json

{ "otp": "123456" }

{
  "status": "success",
  "status_code": 200,
  "data": {
    "message": "New recovery codes generated. Your previous codes no longer work.",
    "recovery_codes": ["…10 codes…"]
  }
}

​

Reset 2FA with a recovery code

1. Get a passkey challenge and sign it (see Passkey confirmation).
2. Send one recovery code and the signed challenge:

POST /api/v1/2fa/recover
Content-Type: application/json

{
  "recovery_code": "7KQ2M-X9PTD",
  "passkey": {
    "id": "<base64url credential id>",
    "rawId": "<base64url credential id>",
    "type": "public-key",
    "response": {
      "authenticatorData": "<base64url>",
      "clientDataJSON": "<base64url>",
      "signature": "<base64url>",
      "userHandle": "<base64url or null>"
    }
  }
}

{
  "status": "success",
  "status_code": 200,
  "data": { "message": "2FA has been reset. Set it up again to keep your account protected." }
}

• 2FA is turned off and all remaining recovery codes are deleted;
• the user is emailed a security notice with the time and IP address;
• the user should turn 2FA on again straight away, which gives them a new set of recovery codes.

​

Transaction PIN

​

Set or change the PIN

POST /api/v1/pin/update
Content-Type: application/json

{ "pin": "4821", "old_pin": "1234" }

​

Verify the PIN

POST /api/v1/pin/verify
Content-Type: application/json

{ "pin": "4821" }

​

Reset a forgotten transaction PIN

1. Get a passkey challenge and sign it (see Passkey confirmation).
2. Send the current authenticator code, the new PIN and the signed challenge:

POST /api/v1/pin/reset
Content-Type: application/json

{
  "otp": "123456",
  "pin": "4821",
  "pin_confirmation": "4821",
  "passkey": {
    "id": "<base64url credential id>",
    "rawId": "<base64url credential id>",
    "type": "public-key",
    "response": {
      "authenticatorData": "<base64url>",
      "clientDataJSON": "<base64url>",
      "signature": "<base64url>",
      "userHandle": "<base64url or null>"
    }
  }
}

{
  "status": "success",
  "status_code": 200,
  "data": { "message": "Transaction PIN reset successfully" }
}

​

Passkey confirmation

1. Get a challenge:
   POST /api/v1/passkeys/step-up/options
   
   The response contains data.public_key (rpId, challenge, timeout, allowCredentials). It returns 422 No passkeys registered for this account. when the person has no passkey.
2. Sign it in the browser on a *.yativo.com page:
   const assertion = await navigator.credentials.get({
     publicKey: {
       ...options,
       challenge: base64urlDecode(options.challenge),
       allowCredentials: options.allowCredentials.map((c) => ({ ...c, id: base64urlDecode(c.id) })),
     },
   });
   
3. Send it as passkey:
   const passkey = {
     id: assertion.id,
     rawId: base64urlEncode(assertion.rawId),
     type: assertion.type,
     response: {
       authenticatorData: base64urlEncode(assertion.response.authenticatorData),
       clientDataJSON: base64urlEncode(assertion.response.clientDataJSON),
       signature: base64urlEncode(assertion.response.signature),
       userHandle: assertion.response.userHandle ? base64urlEncode(assertion.response.userHandle) : null,
     },
   };
   

​

Limits

​

Errors

​

Frontend flow

• 2FA off → “Turn on 2FA” → generate-2fa-secret → enable-2fa → show the recovery codes with “Download” / “Copy” and an “I’ve saved them” checkbox.
• 2FA on → “Generate new recovery codes” (asks for an authenticator code).
• No passkey → prompt “Add a passkey so you can recover your account”.

1. Ask for a recovery code.
2. Call passkeys/step-up/options, sign with navigator.credentials.get().
3. POST /2fa/recover → on success, send the user to turn 2FA on again.

1. Ask for the new PIN twice and the current authenticator code.
2. Call passkeys/step-up/options, sign.
3. POST /pin/reset.

​

Security notes

• Recovery codes, PINs and authenticator secrets are never returned by any other endpoint. Codes and PINs are stored as one-way hashes; the authenticator secret is encrypted at rest.
• A recovery code is accepted only once, and so is the authenticator code sent to pin/reset.
• Every reset is logged and emailed to the account owner. If a user gets an email for a reset they didn’t make, they should contact support at once.
• A user who has lost both their authenticator and their recovery codes, or has no passkey, can’t reset 2FA or the PIN themselves and must contact support.