Skip to content

Two way OTP API

The two way OTP API Identity Provider has been implemented as a Custom API identity provider. That means it follows the same init and complete step flows as a regular Custom API Identity Provider. There are no custom scripts associated with two way OTP API. All of the logic is built into the Token Server.

What is Two way OTP?

A two way One Time Password (OTP) Identity provider generates two random strings. The first one is generated when the user makes initial request for registration. Then the user takes that code to a system that knows the user and enters it. The system uses an api to interact with the Token Server to generate the challenge response code which the user can then enter on their mobile device. The Token Server can then couple the user from the mobile device and the user from the external system.

The API version differs from the browser based version as it can be entirely implemented with native code. Refer to the SDK documentation for details on how to implement two way OTP API.

Example Requests and Responses

1) The user opens the mobile app and selects the Two way OTP API Identity Provider for registration. It makes a request to the init endpoint and yields a result similar to this:

Response from Init

{
  "status": 2000,
  "data": "582115"
}

2) The user then takes the the client_code which is returned as data from the init response and enters it into a system that knows them such as a User Portal and gets the challenge response.

3) The user takes the challenge response and enters it on their mobile device. Here's an example of a request made to the complete endpoint with the challenge response as the data.

Complete Step request

{
  "data": "456867"
}

Two Way OTP Status Codes

Status Description
2000 Token was valid
4001 Invalid Challenge Code Response. User has properly entered the initial code on their portal but probably made a typo when entering the response code.
4002 User initiated the flow and an initial challenge code was generated. That code was never entered on their portal. User should be directed to their portal to enter the challenge code and can then continue the process.
5000 Other error during validation which cannot be recovered from. Clean up actions should trigger