MFA - TOTP

One of the best ways to enhance the security of your Business Account is by enabling MFA (Multi-Factor Authentication) using the TOTP (Time-Based One-Time Password) method.

TOTP generates a temporary, time-sensitive password that is linked to a secret key stored in your authentication app (such as Google Authenticator, Aegis Authenticator, Microsoft Authenticator, or any other compatible app). Once registered, this method securely verifies your identity whenever you access critical endpoints, ensuring strong protection for your account.

The process is simple: first, you will start the TOTP registration, receiving a secret key to be stored in your authentication app. Then, to confirm that you are the one enabling TOTP, you will validate it by providing the email token received in your inbox along with the OTP generated by your authenticator.

Create TOTP

To register your TOTP, simply call the endpoint below. It will return two values: a secret key (to be stored in your authenticator app) and a QR code (which can be scanned for setup). I'll guide you through the process below.

HTTP Post Request

https://api.sandbox.avenia.io:10952/v2/auth/mfa/totp/create

Response Fields

Field	Type	Description
secret	string	The secret key that must be manually entered into your authentication app.
qrCode	string (URL)	A URL that can be converted into a QR Code to scan with your authenticator.

cUrl Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/mfa/totp/create" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "qrCode": "otpauth://totp/EXAMPLE:example@email.com?algorithm=SHA1&digits=6&issuer=EXAMPLE&period=30&secret=XXXXXXXXXXXXXXX"
}

Let's register this data in your authentication application. I'm going to show you Google Authenticator as an example, but you can use any other authenticator; the process is very similar.

After adding the secret to your authenticator, you will receive an email token to validate your TOTP setup.

Validate TOTP

With the email token and OTP generated by your authenticator app, let's validate so that Avenia API actually activates your 2FA.

HTTP Post Request

https://api.sandbox.avenia.io:10952/v2/auth/mfa/totp/validate

Fields

Field	Type	Description
otp	string	The one-time password (OTP) generated by your authenticator app.
emailToken	string	The email verification token sent to your inbox for confirmation.

Here you must pass the OTP from your authenticator app and the email token. Your JSON should look like this:

{
  "otp": "697919",
  "emailToken": "999999"
}

A request example for validating your TOTP:

curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/mfa/totp/validate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "otp": "697919",
  "emailToken": "999999"
}'

That's it, your TOTP has been activated. You are now free to perform operations that require it.

Invalidation and removal of TOTP

For some reason, you want to remove your TOTP? Let’s do it! Remember that when you remove it, the necessary endpoints won’t work because you’ll be removing your TOTP, which is mandatory for certain endpoints. A 24-hour security cooldown will be enforced on operations that require it.

The method is very simple: to remove your TOTP, first call the deactivation endpoint. Then, confirm the removal by providing the email token received in your inbox.

Remove TOTP (STEP 1)

Let's start the process by going to the endpoint below:

HTTP Post Request

https://api.sandbox.avenia.io:10952/v2/auth/mfa/totp/remove/

curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/mfa/totp/remove/" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

You'll get an OK on the endpoint and receive an email token, and you’re ready to go to the next step.

Confirm remove TOTP (STEP 2)

To confirm, simply send a request with your email token in the body. Your TOTP has been removed, and a 24-hour security restriction will be applied.

POST → https://api.sandbox.avenia.io:10952/v2/auth/mfa/totp/remove/confirm

Field

Field	Type	Description
emailToken	string	The email verification token to confirm TOTP removal.

Your JSON should look like this:

{
  "emailToken": "999999"
}

curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/mfa/totp/remove/confirm" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "emailToken": "999999"
}'

Conclusion

In this guide, you have learned how to enable, validate, and remove TOTP-based MFA for your Business Account.

We covered:

• ✅ Registering TOTP – Generating a secret key and QR code for authentication apps.
• ✅ Validating TOTP – Using the OTP from your authenticator along with an email token to activate MFA.
• ✅ Removing TOTP – Initiating and confirming the deactivation process with an email token.

TOTP adds an extra layer of security by requiring a time-sensitive code generated by your authentication app. This ensures that even if someone gains access to your credentials, they won't be able to authenticate without the generated OTP. If you ever need to disable TOTP, a 24-hour security cooldown is enforced to prevent unauthorized removals.

By following this guide, you now have full control over your MFA setup, ensuring strong security while allowing flexibility if changes are needed.