Authentication | Manage Your 2FA Applications

Learn how to manage your 2FA applications. Just follow the steps below.

 

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" \
-d '{ \ 
"alphanumeric": false, \ 
"attempts": 5, \ 
"expire": 1500, \ 
"name": "WEBSITE1", \ 
"pinLength": 6, \ 
"sender": "ACME" \ 
}' \
https://api.tyntec.com/2fa/v1/application/

Basic Example for creating an application without body (JSON)

curl \
-X POST \
-H "apikey: yourApiKey" \
https://api.tyntec.com/2fa/v1/application/

Response to Basic Example for creating an application without body (JSON)

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 
}

Unsuccessful Request Response (JSON)

HTTP/1.1 400 Bad Request
{"message":"Cannot create application with name 'default'","code":"1017","timestamp":1499762022924}

2. Edit an application

You can get a specific application by using the GET HTTP method and the application’s UUID:

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"

* 45bd08a1-228d-4a8b-bbfe-e59309bfa7f6 is the uuid of the specific application for this example.

 

Response to Basic Example for Edit application (JSON)

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
}

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

 

In this request, there are a number of parameters that need to be defined, while others are optional:
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

3. Delete an application

You can delete your application if needed by using the DELETE Http method. You cannot delete the “default” application.

curl \
-X DELETE \
-H  "apiKey: yourApiKey" \
https://api.tyntec.com/2fa/v1/application/45bd08a1-228d-4a8b-bbfe-e59309bfa7f6

* 45bd08a1-228d-4a8b-bbfe-e59309bfa7f6 is the uuid of the specific application for this example.

 

Response to Basic Example for Delete application (JSON)

HTTP/1.1 200 OK

4. Get an application settings

You can get a specific application by using the GET HTTP method and the application’s UUID:

curl \
-X GET \ 
-H  "apiKey: yourApiKey" \
https://api.tyntec.com/2fa/v1/application/2a9a2a1f-ad49-39e4-9a0e-8f2b648ebf83

* 45bd08a1-228d-4a8b-bbfe-e59309bfa7f6 is the uuid of the specific application for this example.

 

Response to Basic Example for Get application (JSON)

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 }

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

 

 

5. Get your applications

To get a list of applications that you have created under your account:

Basic Example for Sending a Message (JSON)

curl \
-H "apikey: yourApiKey" \
https://api.tyntec.com/2fa/v1/application/

Response to Basic Example for Get your Applications (JSON)

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 } 
]

6. Add/Edit a language template

You can add or edit a language template by referring to the application UUID resource and the language you want to add or edit. If you specify also the channel optional parameter, the specific template for this delivery channel will be created

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"

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

* text parameter should be URL encoded

 

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.

Response to Basic Example for add/edit application language template (JSON)

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
}

7. Delete a language template

You can delete a language template by referring to the application UUID resource and the language you want to delete. If you specify also the channel optional parameter, the specific template for this delivery channel will be deleted.

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"

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

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.

Response to Basic Example for delete application language template (JSON)

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
}

8. HTTP response codes

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.

9. Application Entity

A 2FA application consists of the following parameters:

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.