One Time Password OTP API (2.0)

Download OpenAPI specification:Download

DANAConnect: support@danaconnect.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 authentication keys.

The one-time password generation process has two parts:

1. Generation of the OTP Code - Generate 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 (type=1): Contains only digits (0-9)
  • Alphanumeric (type=2): Contains letters and numbers, excluding ambiguous characters (I, O, l, 0, 1)

The OTP is securely hashed using BCrypt before storage and never stored in plain text.

2. Validation of the OTP Code - Validate Service

This is a one-time use code with an expiration date, depending on the expiration time configured during generation. By default, the user can enter the wrong code 5 times before the code is disabled.

Considerations Prior to Using the API

  • The company using this API must have valid OAuth2 credentials in the DANAConnect platform.
  • For security reasons, the user must have the access2api scope enabled. Your DANAConnect Account Manager must ensure this permission is enabled.
  • This API works with Conversations (flows) that have been previously created and are active in the platform. You must have the Conversation ID (conversationId) for this flow.

What is the Conversation ID?

The conversation identification number in DANAConnect can be found on the activation reports page for each flow inside the Conversation Manager. Important: Every time a conversation is reactivated, a new Conversation ID will be generated.

Changes from v1.0

  • Authentication: Now uses OAuth2 JWT Bearer tokens instead of Basic Auth
  • ID Request: Now returns UUID (String) instead of Integer for improved security
  • New Field: otpFieldCode allows specifying the OTP field identifier

OTP Generation

Operations for generating One-Time Password codes. Generates secure OTP codes that are sent through DANAConnect channels.

Generate OTP code

Generates a secure One-Time Password (OTP) code based on the provided parameters.

Features:

  • Supports numeric (type=1) and alphanumeric (type=2) codes
  • Configurable length (3-12 characters)
  • Configurable expiration time (1-3200 seconds)
  • Configurable maximum validation attempts (default: 5)
  • OTP is hashed using BCrypt before storage (never stored in plain text)
  • Returns a UUID-based requestId for subsequent validation

Flow:

  1. Client sends generation request with conversation ID and parameters
  2. Server generates secure OTP code using cryptographic randomness
  3. OTP is sent to the conversation service for delivery
  4. Hashed OTP is stored in database with expiration metadata
  5. Client receives requestId (UUID) to use for validation
Securityoauth2
Request
Request Body schema: application/json

OTP generation request parameters

conversationId
required
integer <int32> >= 1

Conversation ID

required
object

JSON object with field codes as keys and their values

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

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

Time in seconds until the OTP code expires

maxAttempts
integer <int32>
Default: 5

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

otpFieldCode
required
string

Identifier for the OTP field

Responses
200

OTP generation result (check response code for success/failure)

400

Invalid request parameters - validation failed

401

Unauthorized - Invalid or missing JWT token

post/otp/2.0/generate
Request samples
application/json

Generates a 6-digit numeric OTP code valid for 5 minutes

{
  • "conversationId": 824541,
  • "fieldValues": {
    },
  • "type": 1,
  • "length": 6,
  • "expiresInSeconds": 300,
  • "maxAttempts": 5,
  • "otpFieldCode": "SMS_OTP"
}
Response samples
application/json

The OTP was generated and sent to the conversation service

{
  • "requestId": "550e8400-e29b-41d4-a716-446655440000",
  • "code": 1,
  • "description": "Success",
  • "conversationRequestId": "87a9ab9b-5abf-4802-abfa-e7b891d2a042"
}

OTP Validation

Operations for validating One-Time Password codes. Validates OTP codes entered by users against stored hashes.

Validate OTP code

Validates an OTP code entered by the user against the stored hash.

Validation Process:

  1. Client sends the requestId (UUID) and the OTP code entered by user
  2. Server retrieves the stored OTP record by requestId
  3. Server checks if the OTP has expired
  4. Server checks if maximum attempts have been exceeded
  5. Server verifies the OTP code against the stored BCrypt hash
  6. On success, the OTP is marked as used and cannot be reused

Important Notes:

  • Each OTP can only be validated successfully once
  • After maximum failed attempts, the OTP is permanently invalidated
  • The response includes remaining attempts when validation fails due to incorrect code
Securityoauth2
Request
Request Body schema: application/json

OTP validation request with requestId and OTP code

requestId
required
string

OTP Request ID returned from generate endpoint

otpCode
required
string

OTP code entered by the user

Responses
200

OTP validation result (check response code for success/failure)

400

Invalid request parameters - validation failed

401

Unauthorized - Invalid or missing JWT token

post/otp/2.0/validate
Request samples
application/json

Submit the requestId received from generate endpoint along with the OTP code entered by the user

{
  • "requestId": "550e8400-e29b-41d4-a716-446655440000",
  • "otpCode": "123456"
}
Response samples
application/json

The OTP code is correct and has been marked as used

{
  • "requestId": "550e8400-e29b-41d4-a716-446655440000",
  • "code": 1,
  • "description": "Success",
  • "remainingAttempts": null
}