set authenticator as MFA

Set Authenticator as MFA

This endpoint registers a time-based one-time password (TOTP) authenticator application as the multi-factor authentication (MFA) method for a user. The caller must supply valid credentials along with a device token and device name that identify the authenticator being enrolled. An optional CAPTCHA token can be included when the request originates from a web client that enforces bot protection.

Endpoint

POST /api/auth/v2/authenticator

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token} Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when onboarding a user who wants to switch from SMS-based verification to an authenticator app (such as Google Authenticator or Authy) for MFA. This is also the appropriate call when a user replaces their device and needs to re-register a new authenticator. Partners building security settings screens should call this endpoint after the user scans the QR code and confirms their first TOTP code.

Request Body

The request body accepts one of two schemas: a base token request (banking.business.auth.tokenrequest) or an extended captcha token request (banking.business.auth.captchatokenrequest) that adds a captcha object. All fields from the base schema apply in both cases.

Base request example (no CAPTCHA):

{
  "nickName": "jane.doe",
  "password": "S3cur3P@ssw0rd!",
  "tokenDevice": "JBSWY3DPEHPK3PXP",
  "nameDevice": "iPhone 15 Authenticator",
  "smsCode": "847291",
  "typeOperation": "TimeBasedCode"
}

Extended request example (with CAPTCHA):

{
  "nickName": "jane.doe",
  "password": "S3cur3P@ssw0rd!",
  "tokenDevice": "JBSWY3DPEHPK3PXP",
  "nameDevice": "iPhone 15 Authenticator",
  "smsCode": "847291",
  "typeOperation": "TimeBasedCode",
  "captcha": {
    "token": "03AGdBq24PBnE..."
  }
}

Response

200 OK

A 200 response confirms that the authenticator device was successfully registered as the MFA method for the account. The response body for this endpoint returns a success status without a structured payload.

{}

Error Codes

Common Mistakes

• Omitting tokenDevice — this is the TOTP secret from the authenticator app and is required; do not confuse it with the SMS code.
• Sending an empty string for any required field — all four required fields enforce minLength: 1, so blank values will fail validation.
• Using an expired Bearer token — the token lifetime is 10 minutes; refresh via POST /api/auth/refresh before calling this endpoint.
• Setting typeOperation to ShortMessageCode without providing smsCode — if SMS confirmation is part of the enrollment flow, both fields must be present.
• Including captcha in the body without using the captchatokenrequest schema variant — ensure the content type and body structure match the intended schema.

Related Endpoints

• POST /api/auth/v2 — Obtain a Bearer token by authenticating with username, password, and partnerId
• POST /api/auth/refresh — Refresh an existing Bearer token before it expires
• POST /api/auth/v2/sms — Set SMS as the MFA method instead of an authenticator app

Example

curl -X POST https://api.banking.netevia.dev/api/auth/v2/authenticator \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "jane.doe",
    "password": "S3cur3P@ssw0rd!",
    "tokenDevice": "JBSWY3DPEHPK3PXP",
    "nameDevice": "iPhone 15 Authenticator",
    "smsCode": "847291",
    "typeOperation": "TimeBasedCode"
  }'