Authentication | Deliver OTPs

Learn more about OTP (One-time password) and how to send, verify or delete OTPs.

If any questions arise while reading, you can contact us under support@tyntec.com

Deliver OTPs

1. Send OTP to a number

To deliver an OTP to a destination number, make a POST request to the requests resource:

Basic Example for sending an OTP (JSON)

curl \
-X POST \
-H "apikey: yourApiKey" \
https://api.tyntec.com/2fa/v1/otp?number=4412312313

Response to Basic Example for sending an OTP (JSON)

HTTP/1.1 200 OK
{ accountId: 'your account id', 
"applicationId": "2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83",
"otpId": "b3eaee2c-c3c4-4f40-87e5-c21d07905b27",
"number": "+4412312313",
"attemptCount": 0,
"otpStatus": "ACTIVE",
"expire": 1499862186616,
"created": 1499860686616,
"timestampCreated": "2017-07-12T11:58:06.616Z",
"timestampExpire": "2017-07-12T12:23:06.616Z"
}

* 2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83 is the uuid of the default application for this example.

* b3eaee2c-c3c4-4f40-87e5-c21d07905b27 is the uuid of the generated OTP request for this example.

All possible parameters for this operation

https://api.tyntec.com/2fa/v1/otp?number=<number>&applicationId=<applicationid>&via=<via>&country=<country>&language=<language>&text=<text>&otpCode=<otpcode></otpcode></text></language></country></via></applicationid></number>

Parameter	Optional/ Mandatory	Possible Values	Description
number	mandatory	The destination telephone number	The destination telephone number can be in E164 format (with + sign or 00 prefix or without). In case the country code is not present then the API will check the “country” provided and format the number accordingly.
applicationId	optional	The applicationId of the application you would like to use	If you have provisioned a specific setup for an application, you can include the UUID in this parameter and the settings and language templates for this application will be used. If not specified the “default” application will be used.
Via	optional	Possible values AUTO SMS VOICE	You can force a delivery channel by using this parameter. The default is “AUTO” which will use SMS in case of mobile number and VOICE in case of landline.
language	optional	String	The local language should be in ISO 639-1 format https://en.wikipedia.org/wiki/ISO_639-1 In case you want a specific language template to be used instead of the automatic detection, you can specify it using this parameter. By default the API will check the national code of the destination number and will check if a language template exists for this country. If not it will default to the English template (“en” locale).
country	optional	The ISO 3166-1 alpha-2 code of the destination number.	This parameter can be used in case the country code is omitted in the destination number or because you want to be sure that the destination MSISDN number range belongs to the specific country. If it is not you will get a bad request response.
text	optional	The text template to be used for the specific OTP delivery.	In case you want to override the application template, you can specify the text to be delivered. Placeholder {{OTP}} must exist for auto generation of OTP, otherwise otpCode should be specified as parameter
otpCode	optional	The OTP code to be delivered instead of auto generated one.	In case you don’t want the API to auto generate the OTP for you, you can specify it in this parameter.
sender	optional	Sender name for OTP delivery via SMS	In case you want to override the sender set in the application’s configuration, you can specify a sender name for this OTP delivery
caller	optional	Caller id for OTP delivery via Voice	In case you want to override the caller set in the application’s configuration, you can specify a caller id for this OTP delivery
pinLength	optional	Length of the auto generated PIN	In case you want to override the pin length set in the application’s configuration, you can specify a length of the generated PIN for this OTP delivery

2. Verify OTP code

To verify an OTP code, you need to provide the unique otpId that refers the the OTP delivery request and the OTP code the user provided. The operation will verify then if the OTP code used matched the OTP code that was generated for this user.

Basic Example for verifying an OTP (JSON):

curl \
-X POST \
-H "apikey: yourApiKey" \
https://api.tyntec.com/2fa/v1/otp/b3eaee2c-c3c4-4f40-87e5-c21d07905b27/check?otpCode=1234

* b3eaee2c-c3c4-4f40-87e5-c21d07905b27 is the uuid of the generated OTP request for this example.

Response to Basic Example for verifying an OTP (JSON):

HTTP/1.1 202 OK
{ accountId: 'your account id', 
"applicationId": "2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83",
"otpId": "b3eaee2c-c3c4-4f40-87e5-c21d07905b27",
"number": "+4412312313",
"attemptCount": 1,
"otpStatus": "VERIFIED",
"expire": 1499862186616,
"created": 1499860686616,
"timestampCreated": "2017-07-12T11:58:06.616Z",
"timestampExpire": "2017-07-12T12:23:06.616Z"
}

HTTP return codes:

HTTP Code	Description
202 Accepted	The OTP code provided matched the one delivered.
401 Unauthorized	This verification attempt was not valid
403 Forbidden	The OTP code provided is not correct. This signals a final state for this OTP, either because the maximum attempts has been reached or because the OTP expired. You can check the otpStatus in the body response to determine the status.
404 Not Found	The OTP was not found.
410 Gone	This OTP has already being validated. Note once an OTP is validated, even if you request a check against it with the correct OTP or a wrong one you will already get this HTTP response code.
500 Internal Server Error	Unexpected error.

3. Get delivery events for OTP

You can query the events endpoint of an otp delivery instance to get back a list of events reported for this delivery.

Basic example of getting events for OTP delivery:

curl \
-X GET \
-H "apikey: yourApiKey" \
https://api.tyntec.com/2fa/v1/otp/b3eaee2c-c3c4-4f40-87e5-c21d07905b27/events

* b3eaee2c-c3c4-4f40-87e5-c21d07905b27 is the uuid of the generated OTP request for this example.

Response to Basic Example for getting OTP status (JSON)

HTTP/1.1 200 OK
[ { type: 'INITIAL_OTP_REQ',
created: 1502699988995,
timestampCreated: '2017-08-14T08:39:48.995Z' },
{ type: 'OTP_VERIFY_OK',
created: 1502700284084,
timestampCreated: '2017-08-14T08:44:44.084Z' },
{ statusText: 'delivered',
type: 'OTP_SMS_RES',
smsCode: '0000',
created: 1502699992946,
timestampCreated: '2017-08-14T08:39:52.946Z' },
{ status: 'success',
type: 'DELIVER_OTP_RES_OK',
created: 1502699989105,
timestampCreated: '2017-08-14T08:39:49.105Z' } ]

Field	Description
status	possible values: success/failed/null
statusText	The status reported by the deivery system
type	Refere to the next table regarding all event types
sipCode	In case of voice delivery the sip return code will be listed here
smsCode	In case of sms delivery the sms return code will be listed here
created	Epoch time
timestampCreated	Timestamp in string format UTC

Event type	Description	Example
INITIAL_OTP_REQ	Marks the initial OTP request made as API call	{ type: ‘INITIAL_OTP_REQ’, created: 1502699988995, timestampCreated: ‘2017-08-14T08:39:48.995Z’ }
DELIVER_OTP_RES_OK	Marks the successful result for delivery towards the channel	{ status: ‘success’, type: ‘DELIVER_OTP_RES_OK’, created: 1502699989105, timestampCreated: ‘2017-08-14T08:39:49.105Z’ }
DELIVER_OTP_RES_FAIL	Marks the failed result for delivery towards the channel	{ status: ‘failed’, type: ‘DELIVER_OTP_RES_FAIL’, created: 1502699989105, timestampCreated: ‘2017-08-14T08:39:49.105Z’ }
RESEND_OTP_RES_OK	Marks the successful result for delivery towards the channel for an OTP resend	{ status: ‘success’, type: ‘RESEND_OTP_RES_OK’, created: 1502699989105, timestampCreated: ‘2017-08-14T08:39:49.105Z’ }
RESEND_OTP_RES_FAIL	Marks the failed result for delivery towards the channel for an OTP resend	{ status: ‘failed’, type: ‘RESEND_OTP_RES_FAIL’, created: 1502699989105, timestampCreated: ‘2017-08-14T08:39:49.105Z’ }
OTP_SMS_RES	Marks the delivery report coming for a sms delivery	{ statusText: ‘delivered’, type: ‘OTP_SMS_RES’, smsCode: ‘0000’, created: 1502699992946, timestampCreated: ‘2017-08-14T08:39:52.946Z’ }
OTP_VOICE_RES	Marks the delivery report coming for a voice call delivery	{ statusText: ‘ok’, type: ‘OTP_VOICE_RES’, created: 1502700988376, timestampCreated: ‘2017-08-14T08:56:28.376Z’ }
OTP_VERIFY_FAIL	Marks the event when there was a failed attempt to verify an OTP code	{ type: ‘OTP_VERIFY_FAIL’, created: 1502700284084, timestampCreated: ‘2017-08-14T08:44:44.084Z’ }
OTP_VERIFY_OK	Marks the event when there was a successful attempt to verify an OTP code	{ type: ‘OTP_VERIFY_OK’, created: 1502700284084, timestampCreated: ‘2017-08-14T08:44:44.084Z’ }

4. Get OTP status

To get the status of the OTP, you can use this API operation.

Basic Example for getting OTP status (JSON)

curl \
-X GET \
-H "apikey: yourApiKey" \
https://api.tyntec.com/2fa/v1/otp/b3eaee2c-c3c4-4f40-87e5-c21d07905b27

* b3eaee2c-c3c4-4f40-87e5-c21d07905b27 is the uuid of the generated OTP request for this example.

Response to Basic Example for getting OTP status (JSON)

HTTP/1.1 200 OK
{ accountId: 'your account id', 
"applicationId": "2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83",
"otpId": "b3eaee2c-c3c4-4f40-87e5-c21d07905b27",
"number": "+4412312313",
"attemptCount": 1,
"otpStatus": "ACTIVE",
"expire": 1499862186616,
"created": 1499860686616,
"timestampCreated": "2017-07-12T11:58:06.616Z",
"timestampExpire": "2017-07-12T12:23:06.616Z"
}

5. Resend an OTP code

To resend an OTP code, in case the end user didn’t receive the OTP in a reasonable timeframe you can use this operation to resend the same OTP code.

The OTP code delivered will be the same as the original one. You have the option to choose a different delivery channel.

Basic Example for resending an OTP code (JSON):

curl \
-X POST \
-H "apikey: yourApiKey" \
https://api.tyntec.com/2fa/v1/otp/b3eaee2c-c3c4-4f40-87e5-c21d07905b27?via=VOICE

* b3eaee2c-c3c4-4f40-87e5-c21d07905b27 is the uuid of the generated OTP request for this example.
* in this example we force the API to re send the OTP via voice channel.

Parameter	Optional/Mandatory	Possible values	Description
Via	Optional	AUTO SMS VOICE	You can force a delivery channel by using this parameter. The default is “AUTO” which will use SMS in case of a mobile number and VOICE in case of a landline number.
sender	Optional	Sender name for OTP delivery via SMS	In case you want to override the sender set in the application’s configuration, you can specify a sender name for this OTP delivery
caller	Optional	Caller id for OTP delivery via Voice	In case you want to override the caller set in the application’s configuration, you can specify a caller id for this OTP delivery

Response to Basic Example for resending an OTP code (JSON)

HTTP/1.1 200 OK
{ accountId: 'your account id',
"applicationId": "2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83",
"otpId": "b3eaee2c-c3c4-4f40-87e5-c21d07905b27",
"number": "+4412312313",
"attemptCount": 1,
"otpStatus": "ACTIVE",
"expire": 1499862186616,
"created": 1499860686616,
"timestampCreated": "2017-07-12T11:58:06.616Z",
"timestampExpire": "2017-07-12T12:23:06.616Z"
}

6. Delete OTP status

To delete the status of the OTP, you can use this API operation.
Basic Example for deleting an OTP (JSON)

curl \
-X DELETE \
-H "apikey: yourApiKey" \
https://api.tyntec.com/2fa/v1/otp/b3eaee2c-c3c4-4f40-87e5-c21d07905b27

* b3eaee2c-c3c4-4f40-87e5-c21d07905b27 is the uuid of the generated OTP request for this example.

Response to Basic Example for deleting an OTP (JSON)

HTTP/1.1 200 OK
{ accountId: 'your account id', 
"applicationId": "2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83",
"otpId": "b3eaee2c-c3c4-4f40-87e5-c21d07905b27",
"number": "+4412312313",
"attemptCount": 1,
"otpStatus": "ACTIVE",
"expire": 1499862186616,
"created": 1499860686616,
"timestampCreated": "2017-07-12T11:58:06.616Z",
"timestampExpire": "2017-07-12T12:23:06.616Z"
}

7. OTP entity

When you send an OTP the API will reply with an entity for the specific OTP delivery request.

Parameter	Explanation	Default value
AccountId	Type: “String” This is your accountId in the tyntec system. You cannot change this value.	Your 2FA accountId
ApplicationId	Type: “UUID” This is a UUID that identifies the specific application that was used to deliver this OTP.
otpId	Type: “UUID” The unique id that identified this OTP delivery request.	A random UUID created by tyntec
created	Type: “Integer” The time that this OTP request was created in milliseconds.	now()
expire	Type: “Integer” The time that this OTP will expire in milliseconds.	Now() + the “expire” attribute of the application
number	Type: “String” The telephone number that was used as destination for this OTP delivery request. In E164 format.
attemptCount	Type: “Integer” The number of attempts made for this OTP to be validated.
otpStatus	Type: “String” The OTP status. Possible values: “ACTIVE” – The OTP is still active VERIFIED – The OTP was verified successfully EXPIRED – The OTP expired TOO_MANY_ATTEMPTS – The OTP validation requests exceeded the maximum allowed by the application configuration.
timestampCreated	Type: “Timestamp” The string timestamp “created” representation in UTC Z format
timestampExpire	Type: “Timestamp” The string timestamp “expire” representation in UTC Z format

Authenticate

2FA is our robust and feature-rich API that send the passcode to your users phone via the appropriate channel (SMS or voice). Complete with multi-language and customization support. View also our product page to get more information about 2FA.

Deliver OTPS

Authentication | Deliver OTPs

Deliver OTPs

1. Send OTP to a number

2. Verify OTP code

3. Get delivery events for OTP

4. Get OTP status

5. Resend an OTP code

6. Delete OTP status

7. OTP entity