curl \ -X POST \ -H "apikey: yourApiKey" \ -d '{ \ "alphanumeric": false, \ "attempts": 5, \ "expire": 1500, \ "name": "WEBSITE1", \ "pinLength": 6, \ "sender": "ACME" \ }' \ https://api.tyntec.com/2fa/v1/application/
Manage Your 2FA Applications
1. Create an application
To create an application you can either use the target URI with a POST HTTP request or also include in your request body the application parameters that will deviate from the default values.
Basic Example for creating an application with body (JSON)
curl \ -X POST \ -H "apikey: yourApiKey" \ https://api.tyntec.com/2fa/v1/application/
HTTP/1.1 200 OK { accountId: 'your account id', applicationId: '4b5b626d-d79f-3c88-a139-cac021a95a7e', name: 'App-1499676371415', pinLength: 4, alphanumeric: false, attempts: 3, expire: 300, template: { en: 'OTP code: {{OTP}}. Valid for {{SEC}} seconds.' }, sender: 'VERIFY', created: 1499676371415 }
HTTP/1.1 400 Bad Request {"message":"Cannot create application with name 'default'","code":"1017","timestamp":1499762022924}
curl \ -H "apiKey: yourApiKey" \ -X POST "https://api.tyntec.com/2fa/v1/application/2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83?pinLength=5&attempts=5&expire=1500&sender=ACME"
HTTP/1.1 200 OK { "accountId": "yourAccountId", "applicationId": "2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83", "name": "default", "pinLength": 5, "alphanumeric": false, "attempts": 5, "expire": 1500, "template": { "en": "OTP code: {{OTP}}. Valid for {{SEC}} seconds.", "en-voice": "Your OTP code is {{OTP}} . Repeat of OTP Code: {{OTP}}" }, "sender": "ACME", "created": 1499695238322 }
Parameter | Optional/ Mandatory | Possible Values | Description |
---|---|---|---|
applicationId | mandatory | The applicationId of the application you would like to edit | This parameter is part of the URI following the pattern ${baseURL}/application/{applicationId} You can specify "default" to reference the default application |
name | optional | The name for this application. Only “default” is not allowed | This parameter represents the custom name for this application. Only “default” is reserved as it maps to the default application for this user. |
pinLength | optional | Integer. 4-11 allowed values | The length of the auto generated PIN length. |
alphaNumeric | optional | boolean | If this parameter is true then the autogenerated PIN will be an alphanumeric PIN in small case. By default this false is false, and the PIN is generated with numeric values. |
attempts | optional | Integer | This parameter controls how many attempts the user is allowed to have to validate a delivered OTP. |
expire | optional | Integer | This parameter controls the expiration time in seconds after the first OTP delivery request. |
sender | optional | String | This parameter is controlling the sender name upon SMS delivery. |
caller | optional | String | This parameter is used to define a number as caller for the voice calls. Adding this will improve the call success ratio, as some operatos filters anonymous calls |
curl \ -X DELETE \ -H "apiKey: yourApiKey" \ https://api.tyntec.com/2fa/v1/application/45bd08a1-228d-4a8b-bbfe-e59309bfa7f6
HTTP/1.1 200 OK
curl \ -X GET \ -H "apiKey: yourApiKey" \ https://api.tyntec.com/2fa/v1/application/2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83
HTTP/1.1 200 OK { accountId: 'your account id', applicationId: '2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83', name: 'default', pinLength: 4, alphanumeric: false, attempts: 3, expire: 300, template: { en: 'OTP code: {{OTP}}. Valid for {{SEC}} seconds.', 'en-voice': 'Your OTP code is {{OTP}} . Repeat of OTP Code: {{OTP}}' }, sender: 'VERIFY', created: 1499695238322 }
curl \ -H "apikey: yourApiKey" \ https://api.tyntec.com/2fa/v1/application/
HTTP/1.1 200 OK [ { accountId: 'your account id', applicationId: '4b5b626d-d79f-3c88-a139-cac021a95a7e', name: 'default', pinLength: 4, alphanumeric: false, attempts: 3, expire: 300, template: { en: 'OTP code: {{OTP}}. Valid for {{SEC}} seconds.' }, sender: 'VERIFY', created: 1499676371415 } ]
curl \ -X POST "https://api.tyntec.com/2fa/v1/application/e1f7b288-3f05-4ea6-838c-dac09eb25252/language?language=de&text=OTP-Code%3A%20%7B%7BOTP%7D%7D%20Einen%20sch%C3%B6nen%20Tag%20noch.%20OTP-Code%3A%20%7B%7BOTP%7D%7D&channel=VOICE" \ -H "accept: application/json" \ -H "apiKey: yourApiKey"
Parameter | Optional/ Mandatory | Possible Values | Description |
---|---|---|---|
applicationId | mandatory | The applicationId of the application you would like to edit | This parameter is part of the URI following the pattern ${baseURL}/application/{applicaitonId} You can specify "default" to reference the default application |
language | mandatory | String | The language locale should be in ISO 639-1 format https://en.wikipedia.org/wiki/ISO_639-1 |
text | mandatory | String | The text template for the specific language. Placeholder {{OTP}} must exist at least once. {{SEC}} is an optional placeholder that will replace the “expire” parameter for this application. |
channel | optional | Enum. Possible values: SMS VOICE | The optional parameter is set in case you want for the same language to have different template depending on the delivery channel. |
HTTP/1.1 200 OK { "accountId": "yourAccountId", "applicationId": "e1f7b288-3f05-4ea6-838c-dac09eb25252", "name": "My web app 2", "pinLength": 6, "alphanumeric": false, "attempts": 5, "expire": 1000, "template": { "de": "OTP-Code: {{OTP}} Einen schönen Tag noch", "en": "OTP code: {{OTP}}. Valid for {{SEC}} seconds.", "de-voice": "OTP-Code: {{OTP}} Einen schönen Tag noch. OTP-Code: {{OTP}}" }, "sender": "Tyntec", "created": 1499245230960 }
curl \ -X DELETE "https://api.tyntec.com/2fa/v1/application/e1f7b288-3f05-4ea6-838c-dac09eb25252/language?language=de&channel=VOICE" \ -H "accept: application/json" \ -H "apiKey: yourApiKey"
Parameter | Optional/ Mandatory | Possible Values | Description |
---|---|---|---|
applicationId | mandatory | The applicationId of the application you would like to edit | This parameter is part of the URI following the pattern ${baseURL}/application/{applicaitonId} You can specify "default" to reference the default application |
language | mandatory | String | The language locale should be in ISO 639-1 format https://en.wikipedia.org/wiki/ISO_639-1 |
channel | optional | Enum. Possible values: SMS VOICE | The optional parameter is set in case you want for the same language to have different template depending on the delivery channel. |
HTTP/1.1 200 OK { "accountId": "yourAccountId", "applicationId": "e1f7b288-3f05-4ea6-838c-dac09eb25252", "name": "My web app 2", "pinLength": 6, "alphanumeric": false, "attempts": 5, "expire": 1000, "template": { "de": "OTP-Code: {{OTP}} Einen schönen Tag noch", "en": "OTP code: {{OTP}}. Valid for {{SEC}} seconds.", "de-voice": "OTP-Code: {{OTP}} Einen schönen Tag noch. OTP-Code: {{OTP}}" }, "sender": "Tyntec", "created": 1499245230960 }
HTTP Code | Message | Description |
---|---|---|
200 OK | The HTTPS request was accepted. | |
400 Bad Request | The request could not be validated | The HTTPS request failed to pass the validation, i.e., one or more of the required parameters of the request are empty/missing/contradictory/invalid. The given message provides more information as to why the validation failed. |
401 Unauthorized | ApiKey missing | ApiKey is missing in the request. You have to include it either as HTTP header with key “apiKey” or as query parameter in your request. |
403 Forbidden | Apikey is wrong. | The API key provided is not authorized. |
404 Not Found | The requested resource could not be found. | The requested URI is non-existent. |
405 Method Not Allowed | Invalid request method. | The request contains an invalid HTTP method (POST/GET). |
406 Not Acceptable | The content-type is not supported. Allowed values are "application/json". | The request is not JSON format or the HTTP header reads "Content-Type". |
415 Unsupported Media Type | The media type is not supported. Allowed media-type is "application/json". | The request is not JSON format or the HTTP header reads "Accept". |
500 Internal Server Error | Please retry. If error persists, please contact customer support. | Unexpected error. |
Parameter | Explanation | Default value |
---|---|---|
alphanumeric | Type: “boolean” The type of generated PIN. If set to true then a random alphanumeric PIN will be generated, in case of false a numeric PIN will be generated. This value can be set by the user. | false |
attempts | Type: “Integer” The number of attempts that are allowed to verify a delivered OTP. After this number of attempts, the OTP will be invalid. This value can be set by the user. | 3 |
expire | Type: “Integer” The value in seconds until the delivered OTP expires. After expiration, the OTP is not valid anymore. This value can be set by the user. | 300 |
created | Type: “Long” The time in milliseconds that this application was created. This value cannot be set by the user. | Now() |
template | Type: “Map” A key-value map that contains the language (in ISO 639-1 format https://en.wikipedia.org/wiki/ISO_639-1) and the template. The template must include the {{OTP}} placeholder. {{SEC}} placeholder replaces the “expire” to the template and is not mandatory to be included. This value can be changed by the user by a specific API operation. | { "en": "OTP code: {{OTP}}. Valid for {{SEC}} seconds." } |
sender | Type: “String” The sender name that will be used for SMS delivery. This value can be set by the user. | “VERIFY” |
caller | Type: “String” The caller id to be used for voice calls. This value can be set by the user. |