OTP Engine

Get Client Config

url:

GET /v1/oidc/config

Header:

Authorization: Basic <base64(client_id:client_secret)>

Response:

{
  "otp_expiry": 180,   
  "otp_max_invalid_attempts": 3,   
  "otp_length": 5,   
  "otp_request_interval": 60,   
  "regenerate_otp": false,   
  "timestamp": "2023-06-19T07:02:07Z",   
  "access_token_lifespan": 7776000,   
  "refresh_token_max_lifespan": 7862400,   
  "refresh_token_max_reuse": 13
}

Configuration Field Descriptions

Field	Type	Description
otp_expiry	int	OTP expiration. In seconds
otp_max_invalid_attempts	int	This is a numerical value that specifies the maximum number of incorrect OTP attempts a user is allowed before some security action is triggered. For example, if you set it to 3, a user can enter the OTP incorrectly three times before additional security measures,such as locking the user out, are applied. the user can do next request depens on otp_request_interval duration.
otp_length	int	The OTP length determines how many digits or characters are included in the OTP
otp_request_interval	int	Specifies the time interval in seconds, during which a user can request or generate a new One-Time Password (OTP) after their previous OTP request or generation. This parameter helps control how frequently OTPs can be requested to enhance security and prevent abuse.
regenerate_otp	bool	True: When "regenerate_otp" is set to true, it means that each time it is requested, a new OTP will be generated. This is often used for security reasons to ensure that the OTP is only valid for a single use or for a short period of time. Once the OTP is generated and sent to the user, it cannot be used again. False: When "regenerate_otp" is set to false, it means that the same OTP value will be provided until it is used . In this case, the OTP remains valid for a longer duration or until the user successfully authenticates using it.
access_token_lifespan	int	Max time before an access token is expired. In seconds
refresh_token_max_lifespan	int	Max time before a refresh token is expired. In seconds
refresh_token_max_reuse	int	Maximum number of times a refresh token can be reused. Default Used is 0, so when its set to 0 the refresh token can be used for request new access token once and cannot be reused. If the value is 1, the refresh token can be used for request new access token once and Reuse it Once. So on and so forth.

Login

Goto Here If you want to integrate with our login

OTP with Basic Auth

To request and validate OTP using otp with basic auth flow, you need to send base64(client_id:client_secret) as basic auth token. Here's the Example Flow Use Case:

API Endpoints

Request OTP

URL:

POST /v1/passwordless/start

Header:

Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/json

Request Body:

{
  "username": "081200010002"
}

Success (200) Response Body:

{
  "username": "081200010002",
  "otp": "123456",
  "timestamp": "2023-01-01T00:00:00Z"
}

Failed (400) Response Body:

{
    "error": "invalid_body",
    "error_description": "Invalid Request Body",
    "timestamp": "2023-08-21T02:44:53Z"
}

List Of Possible Response

http status code	error code	message
500	unexpected_error	Something Went Wrong
400	invalid_request_body	Invalid Request, Please Check Your Request Body
400	invalid_request_body	Please Enter a valid username
401	invalid_client_credential	Invalid Client Credentials
401	identifier_has_active_verification	User has Active OTP

Validate OTP

URL:

POST /v1/passwordless/validate

Header:

Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/json

Request Body:

{
  "username": "081200010002",
  "otp": "123456"
}

Success (200) Response Body:

{
  "message": "OTP Validated Successfully",
  "timestamp": "2023-01-01T00:00:00Z"
}

Failed (400) Response Body:

{
  "error": "invalid_otp",
  "error_description": "OTP is Invalid",
  "timestamp": "2023-01-01T00:00:00Z",
  "metadata": {
    "invalid_attempt": 2,
    "max_invalid_attempt": 3
  }
}

List Of Possible Response

http status code	error code	message
500	unexpected_error	Something Went Wrong
400	invalid_request_body	Invalid Request, Please Check Your Request Body
400	invalid_request_body	Please Enter a valid username
400	verification_not_found	Verification Not Found
400	wrong_otp_request_limit	Wrong OTP Limit Request Exceeded
400	invalid_otp	OTP is Invalid
400	verification_is_expired	Verification Expired
400	used_otp	OTP is Already Used
400	invalid_otp_config_changed	OTP is Invalid, Please Request New OTP
401	invalid_client_credential	Invalid Client Credentials
401	identifier_has_active_verification	User has Active OTP