curl \ -X POST \ -H "apikey: yourApiKey" \ https://api.tyntec.com/2fa/v1/otp?number=4412312313
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" }
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
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 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. |
curl \ -X GET \ -H "apikey: yourApiKey" \ https://api.tyntec.com/2fa/v1/otp/b3eaee2c-c3c4-4f40-87e5-c21d07905b27/events
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' } |
curl \ -X GET \ -H "apikey: yourApiKey" \ https://api.tyntec.com/2fa/v1/otp/b3eaee2c-c3c4-4f40-87e5-c21d07905b27
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
| 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 |
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" }
curl \ -X DELETE \ -H "apikey: yourApiKey" \ https://api.tyntec.com/2fa/v1/otp/b3eaee2c-c3c4-4f40-87e5-c21d07905b27
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" }
| 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 |
