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. |