Authentication with One Time Password (OTP)

Updated on 30 Apr 2020

Brief Description

Authentication with OTP, aka two-factor authentication (2FA) is an additional feature provided by System Operator using SDK.Finance. It is a superset of a traditional user/password authentication and could be switched ON and OFF as desired. To provide this type of authentication the system needs to have some email capability or have access to telephony.

With this type of authentication, the user is not immediately served with the Authorization token. Instead, System Operator generates an additional random one-time password and delivers it to the user either to the email address or as a cell phone number provided during initial registration.

Actors

  1. External Entity that can interact with System Operator API acting as a registered System Operator User.
  2. System Operator running SDK.Finance software and exposing the portfolio of financial APIs.
  3. Provider of email or telephone communication channel.

Preconditions

  1. There is a valid registered System User in System Operator Data Repository.
  2. There is a registered telephone number or email address for the System Operator User.

Basic Flow – by default this flow assumes that External Entity sends Requests to System Operator Endpoints and System Operator sends back Responses to External Entity.

  1. External Entity sends an Authentication request to System Operator API Endpoint.

API Endpoint:: https://sdkfinance.app/api/ui/#!/Authorization/login

Request body example:



   "login":"string",

   "password":"string"

}
  1. System Operator performs credentials validation. If credentials are NOT valid, corresponding error message is sent back
  2. If credentials are valid, System Operator generates a random One Time Password (OTP) and saves it.
  3. System Operator sends OTP to an individual’s email address or to the phone number registered during registration.
  4. System Operator returns to External Entity generated OTP.
  5. External Entity somehow obtains OTP. If OTP has not arrived, External Entity sends a request and Steps 4 and 5 repeated.
  6. External Entity sends a request to System Operator with the OTP obtained from an external channel.

API endpoint: https://sdkfinance.app/api/ui/#!/Authorization/Confirmation_of_an_authorization_using_one_time_password

Request BODY



   "login":"user1",

   "password":"otp-password"

}
  1. System Operator receives OTP from the External Entity and matches it with the earlier saved OTP.
  2. If there is a match, System Operator generates and saves a Security TOKEN. If there is NO match, the corresponding error message is sent back.
  3. System Operator returns Security TOKEN to External Entity.

Example of System Operator response:

{

   "status":"ok",

   "message":"string",

   "action":"TOKEN_CREATED",

   "authorizationToken":{

      "token":"string",

      "expiresAt":"2018-10-30T08:59:14.386Z"

   },

   "members":[

      {

         "role":"string",

         "user":{

            "id":"string",

            "name":"string"

         },

         "organization":{

            "id":"string",

            "type":"string",

            "name":"string",

            "identificationStatus":"string",

            "contract_info":{

               "id":"string",

               "personType":"base"

            }

         },

         "permissions":[

            "string"

         ],

         "token":{

            "token":"string",

            "expiresAt":"2018-10-30T08:59:14.386Z"

         }

      }

   ]

}

Optional Flow with Web Browser UI

  1. An individual using a web browser or mobile application requests a Login page.
  2. System Operator returns a page with 2 input fields  – user ID and password.
  3. An individual enters credentials – user ID and password and sends to System Operator.

API  endpoint: https://sdkfinance.app/api/ui/#!/Authorization/login

Request BODY



   "login":"string",

   "password":"string"

}
  1. System Operator performs the validation. If credentials are NOT valid, step 2 is repeated.
  2. If credentials are valid, System Operator generates a random One Time Password (OTP) and saves it.
  3. The OTP is sent to an individual’s email address or to the phone number.
  4. System Operator sends to the browser the page to input OTP.
  5. An individual checks Email or Telephone number and gets the OTP. If OTP has not arrived, User sends a request and Steps 5 and 6 repeated.
  1. An individual enters OTP on the page and sends to System Operator.

API endpoint: https://sdkfinance.app/api/ui/#!/Authorization/Confirmation_of_an_authorization_using_one_time_password

Request BODY



   "login":"user1",

   "password":"otp-password"

}
  1. System Operator receives OTP and matches it with the saved OTP.
  2. If there is a match, System Operator generates and saves the security TOKEN.
  3. Send Security TOKEN to the browser to use for Authorization of all requests.

Alternative Flow

Steps 1 through 7 get executed.

  1. Individual requests to resend OTP the execution logic returns to step 6 and continues as usual.

Post Conditions

Valid Security TOKEN is available for conducting future operations.

Result example

Example of System Operator response:

{

   "status":"ok",

   "message":"string",

   "action":"TOKEN_CREATED",

   "authorizationToken":{

      "token":"string",

      "expiresAt":"2018-10-30T08:59:14.386Z"

   },

   "members":[

      {

         "role":"string",

         "user":{

            "id":"string",

            "name":"string"

         },

         "organization":{

            "id":"string",

            "type":"string",

            "name":"string",

            "identificationStatus":"string",

            "contract_info":{

               "id":"string",

               "personType":"base"

            }

         },

         "permissions":[

            "string"

         ],

         "token":{

            "token":"string",

            "expiresAt":"2018-10-30T08:59:14.386Z"

         }

      }

   ]

}