Application setup

Create and manage your 2FA application.

The application represents your service. It’s a good practice to have separate applications for separate services. You may also have separate applications for the same service but different use cases. For example, 2FA for login may be represented as one application and 2FA for changing password as another. Separating use cases in different applications will allow you to choose different options and behavior for each use case (like PIN attempts or PIN limits).

Note

Creating an application is the first step of the 2FA setup process. See 2FA Introduction to learn about next steps.

On this page you will find how to:

Resource

https://api.infobip.com/2fa/2/applications

Resource description

Parameter Type Description
name * string 2FA application name.
enabled boolean Indicates if the created application is enabled.
configuration object Created 2FA application configuration.
> pinAttempts integer Number of possible PIN attempts.
Default value: 10
> pinTimeToLive string PIN time to live.
Default value: 15m (Time format)
> verifyPinLimit string Number of PIN verification requests in time interval from one phone number (MSISDN).
Default value: 1/3s (Limit format)
> sendPinPerApplicationLimit string Overall number of requests in time interval for generating a PIN and sending an SMS using single application.
Default value: 10000/1d (Limit format)
> sendPinPerPhoneNumberLimit string Number of requests in time interval for generating a PIN and sending an SMS to one phone number (MSISDN).
Default value: 3/1d (Limit format)
> allowMultiplePinVerifications boolean Default value: true. Tells if multiple PIN verification are allowed.
applicationId string 2FA application ID.
name string 2FA application name.
enabled boolean Indicates if the created application is enabled.

Time format

  • Format: {timeLength}{timeUnit}
  • timeLength: positive integer
  • timeUnit: milliseconds ms, seconds s, minutes m, hours h, days d
  • Examples: 15m, 1h, 2d

Limit format

  • Format: {attempts}/{timeLength}{timeUnit}
  • attempts: positive integer
  • timeLength: positive integer
  • timeUnit: milliseconds ms, seconds s, minutes m, hours h, days d
  • Examples: 10/15m, 2/10s

Create a new application

Use this method to create a new application.

POST https://api.infobip.com/2fa/2/applications

Request example

POST /2fa/2/applications HTTP/1.1
Host: api.infobip.com
Content-Type: application/json
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
    "name":"Test application BASIC",
    "configuration": {
        "pinAttempts": 10,
        "allowMultiplePinVerifications": true,
        "pinTimeToLive": "15m",
        "verifyPinLimit": "1/3s",
        "sendPinPerApplicationLimit": "10000/1d",
        "sendPinPerPhoneNumberLimit": "3/1d"
    },
    "enabled": true
}
POST /2fa/2/applications HTTP/1.1
Host: api.infobip.com
Content-Type: application/xml
Accept: application/xml
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <name>Test application BASIC</name>
    <configuration>
      <pinAttempts>10</pinAttempts>
      <allowMultiplePinVerifications>true</allowMultiplePinVerifications>
      <pinTimeToLive>15m</pinTimeToLive>
      <verifyPinLimit>1/3s</verifyPinLimit>
      <sendPinPerApplicationLimit>10000/1d</sendPinPerApplicationLimit>
      <sendPinPerPhoneNumberLimit>3/1d</sendPinPerPhoneNumberLimit>
    </configuration>
    <enabled>true</enabled> 
</request>
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.infobip.com/2fa/2/applications",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"name\":\"Test application BASIC\",\n  \"configuration\": {\n      \"pinAttempts\": 10,\n      \"allowMultiplePinVerifications\": true,\n      \"pinTimeToLive\": \"15m\",\n      \"verifyPinLimit\": \"1/3s\",\n      \"sendPinPerApplicationLimit\": \"10000/1d\",\n      \"sendPinPerPhoneNumberLimit\": \"3/1d\"\n  },\n  \"enabled\": true\n}",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response:

{
    "applicationId": "797493BB352B7B84588F108CEBAAE43E",
    "name": "Test application BASIC",
    "configuration": {
        "pinAttempts": 10,
        "allowMultiplePinVerifications": true,
        "pinTimeToLive": "15m",
        "verifyPinLimit": "1/3s",
        "sendPinPerApplicationLimit": "10000/1d",
        "sendPinPerPhoneNumberLimit": "3/1d"
    },
    "enabled": true
}
<?xml version='1.0' encoding='UTF-8'?>
<ApplicationResponse>
    <applicationId>2C4A98913CE56B7194E8E45422E6B16C</applicationId>
    <name>Test application BASIC</name>
    <configuration>
        <pinAttempts>10</pinAttempts>
        <allowMultiplePinVerifications>true</allowMultiplePinVerifications>
        <pinTimeToLive>15m</pinTimeToLive>
        <verifyPinLimit>1/3s</verifyPinLimit>
        <sendPinPerApplicationLimit>10000/1d</sendPinPerApplicationLimit>
        <sendPinPerPhoneNumberLimit>3/1d</sendPinPerPhoneNumberLimit>
    </configuration>
    <enabled>true</enabled>
</ApplicationResponse>
{
    "requestError": {
        "serviceException": {
            "messageId": "BAD_REQUEST",
            "text": "[name : may not be null]"
        }
    }
}
{
    "requestError": {
        "serviceException": {
            "messageId": "BAD_REQUEST",
            "text": "[configuration.sendPinPerApplicationLimit : Limit format should be \"{attempts}/{timeLength}{timeUnit}\". Time units can be: ms, s, m, h, d]"
        }
    }
}
{
    "requestError": {
        "serviceException": {
            "messageId": "BAD_REQUEST",
            "text": "[configuration.pinTimeToLive : Time format should be \"{timeLength}{timeUnit}\". Time units can be: ms, s, m, h, d]"
        }
    }
}

List all applications

Use this method to get all 2FA applications for your account.

GET https://api.infobip.com/2fa/2/applications/

Request example

GET /2fa/2/applications HTTP/1.1
Host: api.infobip.com
Content-Type: application/json
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
GET /2fa/2/applications HTTP/1.1
Host: api.infobip.com
Content-Type: application/xml
Accept: application/xml
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.infobip.com/2fa/2/applications",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response:

[
    {
        "applicationId": "0933F3BC087D2A617AC6DCB2EF5B8A61",
        "name": "Test application BASIC 1",
        "configuration": {
            "pinAttempts": 10,
            "allowMultiplePinVerifications": true,
            "pinTimeToLive": "2h",
            "verifyPinLimit": "1/3s",
            "sendPinPerApplicationLimit": "10000/1d",
            "sendPinPerPhoneNumberLimit": "3/1d"
        },
        "enabled": true
    },
    {
        "applicationId": "5F04FACFAA4978F62FCAEBA97B37E90F",
        "name": "Test application BASIC 2",
        "configuration": {
            "pinAttempts": 12,
            "allowMultiplePinVerifications": true,
            "pinTimeToLive": "10m",
            "verifyPinLimit": "2/1s",
            "sendPinPerApplicationLimit": "10000/1d",
            "sendPinPerPhoneNumberLimit": "5/1h"
        },
        "enabled": true
    },
    {
        "applicationId": "B450F966A8EF017180F148AF22C42642",
        "name": "Test application BASIC 3",
        "configuration": {
            "pinAttempts": 15,
            "allowMultiplePinVerifications": true,
            "pinTimeToLive": "1h",
            "verifyPinLimit": "30/10s",
            "sendPinPerApplicationLimit": "10000/3d",
            "sendPinPerPhoneNumberLimit": "10/20m"
        },
        "enabled": true
    }
]
<?xml version='1.0' encoding='UTF-8'?>
<ApplicationResponse>
    <item>
        <applicationId>CB83150668AAE1E0FA2AA4B477A91487</applicationId>
        <name>Test application BASIC 1</name>
        <configuration>
            <pinAttempts>2</pinAttempts>
            <allowMultiplePinVerifications>true</allowMultiplePinVerifications>
            <pinTimeToLive>15m</pinTimeToLive>
            <verifyPinLimit>1/3s</verifyPinLimit>
            <sendPinPerApplicationLimit>10000/1d</sendPinPerApplicationLimit>
            <sendPinPerPhoneNumberLimit>3/1d</sendPinPerPhoneNumberLimit>
        </configuration>
        <enabled>true</enabled>
    </item>
    <item>
        <applicationId>D4BFBEECD1B83628940EBCAA4753BA5C</applicationId>
        <name>Test application BASIC 2</name>
        <configuration>
            <pinAttempts>10</pinAttempts>
            <allowMultiplePinVerifications>true</allowMultiplePinVerifications>
            <pinTimeToLive>15m</pinTimeToLive>
            <verifyPinLimit>1/3s</verifyPinLimit>
            <sendPinPerApplicationLimit>10000/1d</sendPinPerApplicationLimit>
            <sendPinPerPhoneNumberLimit>3/1d</sendPinPerPhoneNumberLimit>
        </configuration>
        <enabled>true</enabled>
    </item>
    <item>
        <applicationId>2C4A98913CE56B7194E8E45422E6B16C</applicationId>
        <name>Test application BASIC 3</name>
        <configuration>
            <pinAttempts>10</pinAttempts>
            <allowMultiplePinVerifications>true</allowMultiplePinVerifications>
            <pinTimeToLive>15m</pinTimeToLive>
            <verifyPinLimit>1/3s</verifyPinLimit>
            <sendPinPerApplicationLimit>10000/1d</sendPinPerApplicationLimit>
            <sendPinPerPhoneNumberLimit>3/1d</sendPinPerPhoneNumberLimit>
        </configuration>
        <enabled>true</enabled>
    </item>
</ApplicationResponse>

Get single application

Use this method to get the specific 2FA application identified by applicationId.

GET https://api.infobip.com/2fa/2/applications/{applicationId}

Request example

GET /2fa/2/applications/0933F3BC087D2A617AC6DCB2EF5B8A61 HTTP/1.1
Host: api.infobip.com
Content-Type: application/json
Accept: application/json
Authorization: Basic Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
GET /2fa/2/applications/0933F3BC087D2A617AC6DCB2EF5B8A61 HTTP/1.1
Host: api.infobip.com
Content-Type: application/xml
Accept: application/xml
Authorization: Basic Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.infobip.com/2fa/2/applications/0933F3BC087D2A617AC6DCB2EF5B8A61",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response:

{
    "applicationId": "0933F3BC087D2A617AC6DCB2EF5B8A61",
    "name": "Test application BASIC",
    "configuration": {
        "pinAttempts": 10,
        "allowMultiplePinVerifications": true,
        "pinTimeToLive": "2h",
        "verifyPinLimit": "1/3s",
        "sendPinPerApplicationLimit": "10000/1d",
        "sendPinPerPhoneNumberLimit": "3/1d"
    },
    "enabled": true,
    "processId": "B63B57356B996AF0E2EC669EDDD14980"
}
<?xml version='1.0' encoding='UTF-8'?>
<ApplicationResponse>
    <applicationId>D4BFBEECD1B83628940EBCAA4753BA5C</applicationId>
    <name>Test application BASIC</name>
    <configuration>
        <pinAttempts>10</pinAttempts>
        <allowMultiplePinVerifications>true</allowMultiplePinVerifications>
        <pinTimeToLive>15m</pinTimeToLive>
        <verifyPinLimit>1/3s</verifyPinLimit>
        <sendPinPerApplicationLimit>10000/1d</sendPinPerApplicationLimit>
        <sendPinPerPhoneNumberLimit>3/1d</sendPinPerPhoneNumberLimit>
    </configuration>
    <enabled>true</enabled>
    <processId>43529604407430B063A0697754A6DB67</processId>
</ApplicationResponse>
{
    "requestError": {
        "serviceException": {
            "messageId": "APPLICATION_NOT_FOUND",
            "text": "Application with given id cannot be found."
        }
    }
}

Update application

Use this method to update your 2FA application that is already created. Application is identified by applicationId.

PUT https://api.infobip.com/2fa/2/applications/{applicationId}

Request example

PUT /2fa/2/applications/0933F3BC087D2A617AC6DCB2EF5B8A61 HTTP/1.1
Host: api.infobip.com
Content-Type: application/json
Accept: application/json
Authorization: Basic Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
    "name":"Test application BASIC",
    "configuration": {
        "pinAttempts": 10,
        "allowMultiplePinVerifications": true,
        "pinTimeToLive": "120m",
        "verifyPinLimit": "1/3s",
        "sendPinPerApplicationLimit": "10000/1d",
        "sendPinPerPhoneNumberLimit": "3/1d"
    },
    "enabled": true
}
PUT /2fa/2/applications/0933F3BC087D2A617AC6DCB2EF5B8A61 HTTP/1.1
Host: api.infobip.com
Content-Type: application/xml
Accept: application/xml
Authorization: Basic Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <name>Test application BASIC</name>
    <configuration>
        <pinAttempts>10</pinAttempts>
        <allowMultiplePinVerifications>true</allowMultiplePinVerifications>
        <pinTimeToLive>120m</pinTimeToLive>
        <verifyPinLimit>1/3s</verifyPinLimit>
        <sendPinPerApplicationLimit>10000/1d</sendPinPerApplicationLimit>
        <sendPinPerPhoneNumberLimit>3/1d</sendPinPerPhoneNumberLimit>
    </configuration>
    <enabled>true</enabled>
</request>
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.infobip.com/2fa/2/applications/0933F3BC087D2A617AC6DCB2EF5B8A61",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\n  \"name\":\"Test application BASIC\",\n  \"configuration\": {\n      \"pinAttempts\": 10,\n      \"allowMultiplePinVerifications\": true,\n      \"pinTimeToLive\": \"120m\",\n      \"verifyPinLimit\": \"1/3s\",\n      \"sendPinPerApplicationLimit\": \"10000/1d\",\n      \"sendPinPerPhoneNumberLimit\": \"3/1d\"\n  },\n  \"enabled\": true\n}",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response:

{
    "applicationId": "0933F3BC087D2A617AC6DCB2EF5B8A61",
    "name": "Test application BASIC",
    "configuration": {
        "pinAttempts": 10,
        "allowMultiplePinVerifications": true,
        "pinTimeToLive": "2h",
        "verifyPinLimit": "1/3s",
        "sendPinPerApplicationLimit": "10000/1d",
        "sendPinPerPhoneNumberLimit": "3/1d"
    },
    "enabled": true,
    "processId": "B63B57356B996AF0E2EC669EDDD14980"
}
<?xml version='1.0' encoding='UTF-8'?>
<ApplicationResponse>
    <applicationId>D4BFBEECD1B83628940EBCAA4753BA5C</applicationId>
    <name>Test application BASIC</name>
    <configuration>
        <pinAttempts>10</pinAttempts>
        <allowMultiplePinVerifications>true</allowMultiplePinVerifications>
        <pinTimeToLive>2h</pinTimeToLive>
        <verifyPinLimit>1/3s</verifyPinLimit>
        <sendPinPerApplicationLimit>10000/1d</sendPinPerApplicationLimit>
        <sendPinPerPhoneNumberLimit>3/1d</sendPinPerPhoneNumberLimit>
    </configuration>
    <enabled>true</enabled>
    <processId>43529604407430B063A0697754A6DB67</processId>
</ApplicationResponse>
{
    "requestError": {
        "serviceException": {
            "messageId": "BAD_REQUEST",
            "text": "[name : may not be null]"
        }
    }
}
{
    "requestError": {
        "serviceException": {
            "messageId": "BAD_REQUEST",
            "text": "[configuration.sendPinPerPhoneNumberLimit : Limit format should be \"{attempts}/{timeLength}{timeUnit}\". Time units can be: ms, s, m, h, d]"
        }
    }
}
{
    "requestError": {
        "serviceException": {
            "messageId": "BAD_REQUEST",
            "text": "[configuration.pinTimeToLive : Time format should be \"{timeLength}{timeUnit}\". Time units can be: ms, s, m, h, d]"
        }
    }
}
Next: Message template setup