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.

Manage Your 2FA Applications

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.

 

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.