SetUp Common Multi-Factor Secret

SetUp Common Multi-Factor Secret

This endpoint registers the shared secret used to generate Time-Based One-Time Passwords (TOTP) for Multi-Factor Authentication (MFA). When a user enables MFA via an authenticator app such as Google Authenticator or Authy, this call stores the secret that ties the user's account to their authenticator app. The secret is typically provided to the user as a QR code or a manual entry string during the MFA enrollment flow.

Endpoint

POST /settings/MfaSecret

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

Call this endpoint during the MFA setup flow after the user has chosen to use an authenticator app. The secret submitted here will be used by the authenticator app to generate 30-second TOTP codes that are required at login or when performing sensitive account actions. This endpoint should be called once per MFA enrollment; re-enrolling requires submitting a new secret.

Request Body

{
  "multifactorSecret": "JBSWY3DPEHPK3PXP"
}

Response

200 OK

The secret was successfully registered. The response confirms success; no additional payload fields are documented for this endpoint.

{}

Error Codes

Common Mistakes

• Sending an empty string for multifactorSecret — the field has a minLength: 1 constraint and will be rejected with a 400 error.
• Omitting the multifactorSecret field entirely — it is marked required in the schema.
• Using a plain-text or incorrectly encoded secret — authenticator apps expect a valid Base32-encoded secret; submitting a raw or incorrectly formatted value will cause OTP mismatches even if the API accepts the request.
• Calling this endpoint with an expired Bearer token — tokens are valid for 10 minutes; refresh via POST /api/auth/refresh before making the call.

Related Endpoints

• POST /api/auth/v2 — Obtain a Bearer token (username, password, partnerId)
• POST /api/auth/refresh — Refresh an existing Bearer token
• POST /settings/MfaVerify — Verify a TOTP code after MFA secret setup

Example

curl -X POST https://api.banking.netevia.dev/settings/MfaSecret \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "multifactorSecret": "JBSWY3DPEHPK3PXP"
  }'