One Time Passwords

Q: What happens if my customer exceeds the retry attempts?

When Allow Retry is enabled and the Retry Attempts limit is exceeded, the OTP is invalidated and the contact is locked out of new OTP requests for 3 hours. After the 3-hour window, the contact can request a new OTP.

Customers of DailyStory can utilize their DailyStory email and SMS marketing settings to add one time password (OTP) support for their own applications.

What is a one time password?

A One-Time Password (OTP) is a security mechanism where a user is given a password (or numeric code) that is valid for only one login session or transaction. After it's used—or after a short time window—it becomes invalid.

Important

The following content includes examples that use the DailyStory API. An API key is required.

Generating a One Time Password

Make an HTTP POST request to the Send One Time Password API end point. It must include either an email, mobile number or both. If both are present, it will default to an SMS first.

For example:

HTTP POST https://us-s.dailystory.com/api/v1/verification/?email=test@example.com&mobile=15551234567899 HTTP 200 OK { "Status": true, "Message": "", "Response": { "dsid": "3c095687f9c844d58826d5a4e994215d" } }

In this example, the recipient will receive an SMS or email with a 6 character OTP code that is valid for 15 minutes.

Send Cooldown

Once an OTP is sent to a contact, the API enforces a 30-second cooldown before another OTP can be sent to the same contact. A send request made within the cooldown window returns HTTP 200 with an empty response and no OTP is sent.

Recommended

Store the dsid returned from the send request and prompt the user to check their email or SMS before allowing a resend attempt.

Rate Limiting

To prevent abuse, DailyStory enforces a rolling rate limit on OTP generation per contact. More than 10 send requests for the same contact within a 3-hour window will lock further requests with an error; the window is extended on each attempt, so it clears only after 3 hours with no new requests.

HTTP 400 { "Status": false, "Message": "The maximum number of unsuccessful OTP attempts was exceeded.", "Response": {} }

Configurable Options when issuing an OTP

When sending an OTP several options are configurable via the API:

Option	Default	Configurable Bounds
OTP Size - the number of digits used to generate the OTP.	6 digits	4 - 8 digits
Minutes Valid - the OTP must be validated within this many minutes after being generated.	15 minutes	3 - 20 minutes
Cool down - number of seconds before a new OTP can be generated for the recipient	30 seconds	10 seconds - 10 minutes

Validating a One Time Password

To validate an OTP you will need both the OTP code and the dsid associated with the OTP.

Make an HTTP GET request to the following API URL. In the example below the DSID is part of the URL and the otp that was received is passed in as a parameter:

For example, to verify the OTP 629316 for the dsid 3c095687f9c844d58826d5a4e994215d:

GET https://us-1.dailystory.com/api/v1/verification/3c095687f9c844d58826d5a4e994215d?otp=629316 HTTP 200 OK { "Status": true, "Message": "The OTP is valid.", "Response": {} }

If the OTP is invalid, or the validation fails:

HTTP 400 { "Status": false, "Message": "The OTP is invalid.", "Response": {} }

Single-Use

An OTP is immediately invalidated after a successful validation and cannot be reused. Any subsequent validation attempt with the same code will return an invalid response.

Expiry

By default, OTPs are valid for 15 minutes from the time they are generated. An expired OTP returns the same invalid response as an incorrect code — the two cases are not distinguished in the API response.

Configurable Options when validating an OTP

When validating an OTP several options are configurable via the API:

Option	Default	Configurable Bounds
Minutes Valid - the OTP must be validated within this many minutes after being generated.	15 minutes	3 - 20 minutes
Allow Retry - when true, the OTP survives incorrect guesses up to Retry Attempts before being invalidated. When false (default), any incorrect guess immediately invalidates the OTP.	False	Set to true to allow attempts to retry the OTP.
Retry Attempts - when allowed to retry, this determines how many attempts are allowed before lock out.	5	1 - 10

Retry Lockout

When Allow Retry is enabled and the contact exceeds the configured Retry Attempts, the OTP is invalidated and a 3-hour lockout is applied to that contact. During the lockout, new OTP requests for the same contact are rejected until the window expires.

Error Responses

The following table summarizes error conditions returned by the OTP API:

Condition	HTTP Status	Message
Invalid email format	4XX	Cannot send OTP to contact with an invalid email address
Invalid mobile number format	4XX	Cannot send OTP to contact with an invalid mobile phone number
Rate limit exceeded	4XX	The maximum number of unsuccessful OTP attempts was exceeded.
OTP expired	4XX	The OTP is invalid.
OTP incorrect	4XX	The OTP is invalid.
No pending OTP for dsid	4XX	The OTP is invalid.

Frequently Asked Questions

Below are some frequently asked questions about one time passwords in DailyStory. The assume the default configuration, but the behavior may be different based on the parameters used.

What happens when an OTP expires?

After 15 minutes the OTP is no longer valid. Attempting to validate an expired OTP returns the same invalid response as an incorrect code. The user must request a new OTP.

Can the same OTP be used more than once?

No. An OTP is deleted immediately after a successful validation. Any subsequent attempt to use the same code will return an invalid response.

What triggers the rate limit lockout?

More than 10 OTP generation requests for the same contact within a 3-hour window will trigger a lockout. The window is rolling — it is extended on each attempt, so it clears only after 3 hours with no new requests.

Why didn't my customer receive a new OTP?

A 30-second cooldown is enforced between sends to the same mobile number. If a send request is made within that window, the API returns a successful response but no OTP is sent. Ask the customer to wait 30 seconds before requesting a new code.

What happens if an invalid or mismatched OTP is provided during validation?

If an incorrect OTP (e.g., 123456) is submitted and does not match the code assigned to the contact, the current OTP is immediately invalidated. Even if a subsequent attempt uses the correct code, the validation will fail because the previous mismatch triggered a security reset.

What happens if my customer exceeds the retry attempts?

When Allow Retry is enabled and the Retry Attempts limit is exceeded, the OTP is invalidated and the contact is locked out of new OTP requests for 3 hours. After the 3-hour window, the contact can request a new OTP.