Time-Based (TOTP) and One-Time Passwords (OTP)

MBanq's API provides support for OTP (one-time password) and TOTP (time-based one-time password) to enhance security and verify ownership of requested actions. OTP tokens can be delivered to clients through various channels such as email, SMS, or TOTP applications installed on mobile devices like Google Authenticator, Microsoft Authenticator, or Authy. This guide will explain how to request OTP codes, disable OTP requirements, and manage OTP-protected operations.

📘

API References:

• Authorization

Understanding One-Time Password:

Before proceeding with OTP, ensure that the user has the "REQUEST_OTP" permission to send a request for the OTP code. OTP tokens are obtained through the following steps:

Step 1: Request OTP

To request an OTP code, send a POST request to the following endpoint:

POST https://api.cloud.mbanq.com/v1/otp

Example request:

{
  "deliveryMethod": "EMAIL",
  "extendedToken": false
}

Example response:

{
  "expirationTime": {
    "date": [2022, 5, 30],
    "time": {
      "hour": 11,
      "minute": 37,
      "second": 45,
      "nano": 361585000
    }
  },
  "requestTime": {
    "date": [2022, 5, 30],
    "time": {
      "hour": 11,
      "minute": 32,
      "second": 45,
      "nano": 363566000
    }
  }
}

Step 2: Request Token

Once the OTP code is obtained, the user must have the "REQUEST_TOKEN_MFA" permission to request the token by passing the OTP code. This token can be used to access the back office.

POST https://api.cloud.mbanq.com/v1/mfa/requesttoken

Example request:

{
  "deliveryMethod": "EMAIL",
  "token": "29GZT"
}

Example response:

{
  "token": "c9ab5972e29f4575ab5e5413440772f6",
  "validTo": "2022-05-31 11:40:12",
  "validFrom": "2022-05-30 11:40:12"
}

Disabling OTP:

To disable OTP requirements when accessing the back office, the user must have the "BYPASS_TWOFACTOR" permission. This can be done by managing roles and permissions for the user.

User > Manage Roles and Permissions > Select assigned role to client and disable "BYPASS_TWOFACTOR".

OTP Protected Operation:

OTP can be applied to specific GraphQL mutation/query operations to request resources. The following steps explain how to create, retrieve, and update OTP protected operations.

Create an OTP Protected Operation:

To create an OTP protected operation, send a POST request to the following endpoint:

POST https://api.cloud.mbanq.com/v1/otpProtectedOperation

Field Descriptions:

• operation: A GraphQL mutation/query operation.
• expression: Spring Expression Language to apply conditions to OTP protected operation.
• expressionParam: Expression's parameters.
• enable: To enable/disable OTP protected operation.

Example request:

{
  "operation": "submitTransfer",
  "expression": "!(@transferRepository.findById($id).orElseThrow().getBeneficiaryRefId() != null)",
  "

 

Retrieve OTP Protected Operations:

To retrieve OTP protected operations, send a GET request to the following endpoint:

GET https://api.cloud.mbanq.com/v1/otpProtectedOperation

Example response:

{
  "totalFilteredRecords": 1,
  "pageItems": [
    {
      "id": 1,
      "operation": "submitTransfer",
      "expression": "!(@transferRepository.findById($id).orElseThrow().getBeneficiaryRefId() != null)",
      "expressionParam": "$id",
      "enable": true
    }
  ]
}

Update OTP Protected Operations:

To update an OTP protected operation, send a PUT request to the following endpoint:

PUT https://api.cloud.mbanq.com/v1/otpProtectedOperation/1

Example request:

{
  "expression": "!(@transferRepository.findById($transferId).orElseThrow().getBeneficiaryRefId() != null && [email protected](@transferRepository.findById($transferId).orElseThrow().getBeneficiaryRefId()).orElseThrow().isRequireOtp())",
  "expressionParam": "$transferId",
  "enable": false
}

By following these instructions, you can effectively implement OTP and TOTP functionality within your applications, enhancing security and verifying ownership of requested actions.