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' } ]
Event entity
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 Types
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