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:

Authentication

basicAuth

The API uses the same user credential system that is used to enter the DANAConnect platform.
The method used for all DANAConnect APIs is HTTP BASIC AUTH, which is based on login and password authentication.
Login: The login consists of the username concatenated with an @ and followed by the company code.
Login example:

  • Platform username: myuser
  • Company code for the platform: mycompanycode
  • Login for DANAConnect API: myuser@mycompanycode
  • Password: The password you should use for API authentication is the same as you use for login to the DANAConnect platform
Security Scheme Type HTTP
HTTP Authorization Scheme basic

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

Authorizations:
basicAuth
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 ]
Enum: 1 2

OTP code type

Value Type
1 Numeric
2 Alphanumeric
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

Request samples

Content type
application/json

Request an OTP code

{
  • "idConversation": 824541,
  • "values": [
    ],
  • "type": 1,
  • "length": 12,
  • "secondsExpiration": 3000,
  • "maximumTries": 5
}

Response samples

Content type
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

Authorizations:
basicAuth
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

Request samples

Content type
application/json

Validates an OTP code

{
  • "idRequest": 251,
  • "otp": "Rf24sG"
}

Response samples

Content type
application/json

Successful verification result

{
  • "idRequest": 251,
  • "responseCode": "01",
  • "responseDescription": "Success"
}
Next to Conversation API