One Time Password OTP API (1.0)

Download OpenAPI specification:Download

DANAConnect: support@dannaconnect.com URL: https://www.danaconnect.com License: Apache 2.0

This REST API is a service to generate OTP codes for single-use multi-factor keys. The one-time key generation process has two parts, generation and verification:

  1. Generation of the OTP Code - Send Service:
    The code is generated and sent through the different channels of the DANAConnect platform. It is possible to generate two types of codes: numeric and alphanumeric.
  2. Verification of the OTP code - Verify Service:
    This is a one-time use code and has an expiration date, depending on the expiration time that is configured when it is generated. By default, the user can enter the wrong code 5 times, then the code is disabled.

Considerations prior to using the API

  • The company that is going to use the API must have a valid username and password in the DANAConnect platform.
  • For security reasons, the user who is going to use the API must have a special permission. Your DANAConnect Account Manager must ensure that this permission is enabled.
  • This API works on Conversations (flows) that have previously been created and are active in the platform. This means that you must have the Conversation ID (conversationID) for this flow.
    What is the Conversation identification number (conversationID)?
    The conversation identification number in DANAConnect can be found on the activation reports page for each flow inside the Conversation Manager. It is important to mention that every time a conversation is reactivated, a new Conversation ID will be generated.
  • In the database associated with this conversation you must add a short text type field called “OTP” which must be masked for security reasons.

How to find the Conversation ID

For most DANAConnect API requests, you will need to send the Conversation ID as a parameter.
This conversation ID refers to the number assigned to the activation of the flow and can be found by logging into the DANAConnect platform and looking in the activation report for the conversation you need to refer to. It is important to mention that every time a conversation is reactivated, a new Conversation ID will be generated.
Here is a video explaining how to find the conversation ID:

OTP Generation

Operation involved in the generation of the OTP Code

Generates an OTP code (One Time Password)

This service generates the requested One Time Password Code

SecuritybasicAuth
Request
Request Body schema: application/json

JSON with the data required to generate the OTP code

idConversation
required
integer <int32> >= 1

Conversation id

type
required
integer <int32> [ 1 .. 2 ]

OTP code type

Value Type
1 Numeric
2 Alphanumeric
Enum: 1 2
length
required
integer <int32> [ 3 .. 12 ]

Number of characters that the OTP code contains

secondsExpiration
required
integer <int32> [ 1 .. 3200 ]

Time in seconds until the OTP code expires

maximumTries
integer <int32>
Default: 5

Maximum number of failed attempts allowed by the end user. Default is 5

Array of objects (Values)
Responses
200

The server successfully processed the request

400

Incorrect Request. The request did not match the expected format

401

Authentication Error

post/send
Request samples
application/json

Request an OTP code

{
  • "idConversation": 824541,
  • "values": [
    ],
  • "type": 1,
  • "length": 12,
  • "secondsExpiration": 3000,
  • "maximumTries": 5
}
Response samples
application/json

Successful request result

{
  • "idRequest": 251,
  • "responseCode": "01",
  • "responseDescription": "Success",
  • "conversationRequestId": "87a9ab9b-5abf-4802-abfa-e7b891d2a042"
}

OTP Validation

Operation involved in validating the OTP code

Verifies an OTP code (One Time Password)

This service verifies an OTP code previously generated

SecuritybasicAuth
Request
Request Body schema: application/json

JSON with the data required to validate the OTP code

idRequest
required
integer <int32> >= 1

OTP Request ID, given in the response of a past OTP request

otp
required
string non-empty

OTP code

Responses
200

The server successfully verified the request

400

Incorrect Request. The request did not match the expected format

401

Authentication Error

post/verify
Request samples
application/json

Validates an OTP code

{
  • "idRequest": 251,
  • "otp": "Rf24sG"
}
Response samples
application/json

Successful verification result

{
  • "idRequest": 251,
  • "responseCode": "01",
  • "responseDescription": "Success"
}