Infobip 2-factor authentication HTTP API

Base URL

You should submit all requests to the base URL. All the requests are submitted thorough HTTP POST, PUT or GET method. Although you can use HTTP protocol, we strongly recommend you to submit all requests to Infobip SMS API over HTTPS so the traffic is encrypted and the privacy is ensured.

Base URL: https://oneapi.infobip.com/2fa

Authorization

In order to use Infobip 2-FA API, you have to be authorized. We support two types of authorization:

Basic authorization used for service configuration
API key authorization used for client side methods

Basic authorization

We support the Basic authorization with username and password using Base64 encoding variation RFC2045-MIME

The Authorization header is constructed as follows:

Username and password are combined into a string username:password.
The resulting string is encoded using the RFC2045-MIME variant of Base64.
The authorization method and a space "Basic " are put before the encoded string.

Example:

Username: Aladdin
Password: open sesame

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

API key authorization

In order to use a client side methods, you need a valid Infobip API key.

If you don’t have an API key, you can create one using a Generate API key method. When you receive your API key, you should put it in the header after the authorization method and space i.e. "App ".

Example:

API key: e78d84e20207873482d160c1144f7d08-59304bb3-11fa

Authorization: App e78d84e20207873482d160c1144f7d08-59304bb3-11fa

Step by step integration

Service configuration
a. Create and configure your 2FA application
b. Create and configure your 2FA message
c. Generate your API key in order to use Client side methods
Client side methods
a. Generate and send PIN code
b. Verify PIN code
c. Resend PIN code
d. Get PIN code status

Note:
You can also get and update all your 2FA applications and messages.

Application configuration details

PIN Time To Live

PIN time to live represents how long the PIN will be active after it is generated. Within this time frame PIN could be verified. After PIN time to live expires, verification will not be possible. The old PIN will be discarded and the new one should be required.

Default value: 900.000 milliseconds (15 minutes)

Example: Client sets PIN time to live to 45 seconds. If user tries to verify PIN after 50 seconds, the error will occur because PIN time to live has expired. In order to proceed further, the new PIN should be required.

PIN Attempts

PIN attempts represents the number of overall PIN verification requests for one application (service) from one phone number (MSISDN) regardless time interval. If the overall PIN attempts are exceeded, verification will not be possible. The old PIN will be discarded and the new one should be required.

Default value: 10

Example: Client sets PIN attempts to 3. The user enters wrong PIN for 3 times. With the forth attempt he tries to verify the correct PIN, verification will not be possible because PIN attempts are exceeded. In order to proceed further, the new PIN should be required.

Verification Attempts

Verification attempts represents the number of PIN verification requests from one phone number (MSISDN) in a defined verification time interval. If the repeated PIN verification is required before the time interval expires, verification will not be possible. It is necessary that defined verification time interval expires so the PIN verification attempt could be required for the second time.

Default value: 1

Example: Client sets the Verification attempts to 1 and the verification time interval to 3 seconds (explained in the next step). User can try to verify the PIN only once in a 3 seconds from one phone number (MSISDN).

Verification Interval Length

Verification interval length represent a defined time interval in which there can be no multiple (or whatever Verification Attempts is set to) PIN verification attempts. If the repeated PIN verification is requested before the time interval expires, verification will not be possible. It is necessary that defined verification time interval expires so the PIN verification attempt could be processed next time.

Default value: 3.000 milliseconds (3 seconds)

Example: Client sets Verification attempts to 1 and the verification time interval to 3 seconds. User can try to verify the PIN only once in a 3 seconds from one phone number (MSISDN).

Initiation Attempts

Initiation attempts represents the number of requests for generating a PIN and sending an SMS to one phone number (MSISDN) in a defined time interval. If the PIN generation requests from one phone number exceed the initiation attempts for defined time interval, further initiation requests will not be processed. It is necessary that defined time interval expires so the new PIN generation request and SMS sending could be performed.

Default value: 3

Example: Client sets the Initiation attempts to 3 and the time interval to 1 day (explained in the next step). User can require a PIN generation and receiving of an SMS on one phone number max 3 times in one day.

Initiation Interval Length

Initiation interval length represents a time interval in which a defined number of initiation attempts for one phone number (MSISDN) can be realized. If the PIN generation requests from one phone number exceed the initiation attempts for defined time interval, initiation attempts will not be processed. It is necessary that defined time interval expires so the new PIN generation request and sending SMS could be performed.

Default value: 86.400.000 milliseconds (1 day)

Example: Client sets the Initiation attempts to 3 and the Initiation interval length to 1 day. User can request PIN generation and receiving of SMS containing it, for one phone number, maximum 3 times in one day.

API endpoint reference list

Service configuration

Application

Method	Endpoint	Usage	Returns	Authorization
POST	/1/applications	Create an application	application	Basic
PUT	/1/applications/{applicationId}	Update an application	application	Basic
GET	/1/applications	Get all applications	application array	Basic
GET	/1/applications/{applicationId}	Get an application by ID	application	Basic

Message

Method	Endpoint	Usage	Returns	Authorization
POST	/1/applications/{applicationId}/messages	Create a message	message	Basic
PUT	/1/applications/{applicationId}/messages/{messageId}	Update a message	message	Basic
GET	/1/applications/{applicationId}/messages	Get all messages	message array	Basic
GET	/1/applications/{applicationId}/messages/{messageId}	Get a message by ID	message	Basic

API key

Method	Endpoint	Usage	Returns	Authorization
POST	/1/api-key	Generate an API key	apiKey	Basic

Client side methods

Method	Endpoint	Usage	Returns	Authorization
POST	/1/pin	Send a PIN	sendPinResponse	API key
POST	/1/pin/{pinId}/verify	Verify a PIN	verifyPinResponse	API key
POST	/1/pin/{pinId}/resend	Resend a PIN	sendPinResponse	API key
GET	/1/pin/{pinId}/status	Get PIN status	getPinStatusResponse	API key

Verifications

Method	Endpoint	Usage	Returns	Authorization
GET	/1/applications/{applicationId}/verifications	Check is MSISDN verified	verificationStatusObject	API key

API methods usage

Create application

This method allows you to create 2FA application.

For creating a 2FA application you should use the HTTP POST method and the base URL with following end point:

End point: /1/applications

Header field	Description
Authorization	Required. Basic + Base64(username:password).
Content-type	Required. The content type of the request body: `application/json`

Request body parameters

Parameter	Type	Description
name	String	Required. 2FA application name.
enabled	Boolean	Optional. Enabling or disabling 2FA application. You can start 2-factor authentication process only if the 2FA application is enabled. Default value of this parameter is true.
configuration	ApplicationConfiguration	Optional. 2FA application configuration object.

ApplicationConfiguration

Parameter	Type	Description
pinTimeToLive	Long	Optional. PIN time to live (in millis). Default value: 900.000 milliseconds (15 minutes)
pinAttempts	Integer	Optional. Number of possible PIN attempts. Default value: 10
verificationAttempts	Integer	Optional. Number of PIN verification requests from one phone number (MSISDN) in a defined verification time interval. Default value: 1
verificationIntervalLength	Long	Optional. Verification time interval (in millis). Default value: 3.000 milliseconds (3 seconds)
initiationAttempts	Integer	Optional. Number of requests for generating a PIN and sending an SMS to one phone number (MSISDN) in a defined time interval. Default value: 3
initiationIntervalLength	Long	Optional. Time interval in which a defined number of initiation attempts for one phone number (MSISDN) can be realized. Default value: 86.400.000 milliseconds (1 day)

Note:
Find out more about Application configuration details here.

Response format

On success, response header HTTP status code will be 200 OK and the body will contain created application object in JSON format.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to create an application when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Application response body parameters

Parameter	Type	Description
applicationId	String	2FA application ID.
name	String	2FA application name.
enabled	Boolean	Indicates if the created application is enabled.
processId	String	Process tracking ID. You can track conversion rate across 2FA process using multiple parameters (find more information here).
configuration	ApplicationConfiguration	Created 2FA application configuration.

Note:
Find out more about Application configuration details here.

Example

Basic request (required parameters only)

The only required parameter is the name of the application. For a basic usage, you can just set the name of the app and the other parameters will be set to the default values.

POST /2fa/1/applications HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic RkTpGSVR0lUdGVhbZWFt
Content-Type: application/json

{
  "name":"Test applicatio BASIC"
}

Response

{
 "applicationId": "CD265875E3A6EA43478D5F37A635BE4A",
 "name": "Test application BASIC",
 "configuration": {
  "pinTimeToLive": 1800000,
  "pinAttempts": 3,
  "verificationAttempts": 2,
  "verificationIntervalLength": 10000,
  "initiationAttempts": 5,
  "initiationIntervalLength": 1800000,
  "overallInitiationAttempts": 10000,
  "overallInitiationIntervalLength": 86400000,
  "initiationThrottlingProlongationFactor": 1,
  "initiationThrottlingWaitPeriod": 0
 },
 "enabled": true,
 "processId": "F3F887000261BC35CADFADCC947F7EF8"
}

Advanced Request

Advanced usage example represent the request with all available parameters (required and optional).

POST /2fa/1/applications HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic RkTpGSVR0lUdGVhbZWFt
Content-Type: application/json

{
  "name":"Test application ADVANCED",
  "enabled":true,
  "configuration":{
    "pinTimeToLive":2000000,
    "pinAttempts":5,
    "verificationAttempts":3,
    "verificationIntervalLength":12000,
    "initiationAttempts":8,
    "initiationIntervalLength":1800000,
    "overallInitiationAttempts":10000,
    "overallInitiationIntervalLength":86400000
  }
}

Response

{
 "applicationId": "HJ675435E3A6EA43432G5F37A635KJ8B",
 "name": "Test application ADVANCED",
 "configuration": {
  "pinTimeToLive": 2000000,
  "pinAttempts": 5,
  "verificationAttempts": 3,
  "verificationIntervalLength": 12000,
  "initiationAttempts": 8,
  "initiationIntervalLength": 1800000,
  "overallInitiationAttempts": 10000,
  "overallInitiationIntervalLength": 86400000,
  "initiationThrottlingProlongationFactor": 1,
  "initiationThrottlingWaitPeriod": 0
 },
 "enabled": true,
 "processId": "F3F887000261BC35CADFADCC947F7EF8"
}

Update application

This method allows you to update 2FA application that is already created.

For updating a 2FA application you should use the HTTP PUT method and the base URL with following end point:

End point: /1/applications/{applicationId}

Header field	Description
Authorization	Required. Basic + Base64(username:password).
Content-type	Required. The content type of the request body: `application/json`

Request path parameters

Parameters	Type	Description
applicationId	String	Required. 2FA application ID that should be updated.

Request body parameters

Parameter	Type	Description
name	String	Optional. 2FA application name.
enabled	Boolean	Optional. Enabling or disabling 2FA application. You can start 2-factor authentication process only if the 2FA application is enabled. Default value of this parameter is true.
configuration	ApplicationConfiguration	Optional. 2FA application configuration object.

ApplicationConfiguration

Parameter	Type	Description
pinTimeToLive	Long	Optional. PIN time to live (in millis). Default value: 900.000 milliseconds (15 minutes)
pinAttempts	Integer	Optional. Number of possible PIN attempts. Default value: 10
verificationAttempts	Integer	Optional. Number of PIN verification requests from one phone number (MSISDN) in a defined verification time interval. Default value: 1
verificationIntervalLength	Long	Optional. Verification time interval (in millis). Default value: 3.000 milliseconds (3 seconds)
initiationAttempts	Integer	Optional. Number of requests for generating a PIN and sending an SMS to one phone number (MSISDN) in a defined time interval. Default value: 3
initiationIntervalLength	Long	Optional. Time interval in which a defined number of initiation attempts for one phone number (MSISDN) can be realized. Default value: 86.400.000 milliseconds (1 day)

Note:
Find out more about Application configuration details here.

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain updated application object in JSON format.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to update the application when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Response body parameters

Parameter	Type	Description
applicationId	String	2FA application ID.
name	String	2FA application name.
enabled	Boolean	Indicates if the created application is enabled.
processId	String	Process tracking ID. You can track conversion rate across 2FA process using multiple parameters (find more information here).
configuration	ApplicationConfiguration	Created 2FA application configuration.

Note:
Find out more about Application configuration details here.

Example

Request

All body parameters are optional, so only provided parameters will be updated.

PUT /2fa/1/applications/CD265875E3A6EA43478D5F37A635BE4A HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic RkTpGSVR0lUdGVhbZWFt
Content-Type: application/json

{
  "name":"New application name",
  "enabled":true,
  "configuration":{
    "pinAttempts":5
  }
}

Response

{
 "applicationId": "CD265875E3A6EA43478D5F37A635BE4A",
 "name": "New application name",
 "configuration": {
  "pinTimeToLive": 1800000,
  "pinAttempts": 5,
  "verificationAttempts": 2,
  "verificationIntervalLength": 10000,
  "initiationAttempts": 5,
  "initiationIntervalLength": 1800000,
  "overallInitiationAttempts": 10000,
  "overallInitiationIntervalLength": 86400000,
  "initiationThrottlingProlongationFactor": 1,
  "initiationThrottlingWaitPeriod": 0
 },
 "enabled": true,
 "processId": "F3F887000261BC35CADFADCC947F7EF8"
}

Get application(s)

This method allows you to get all 2FA applications for your account. Also, you can get just one 2FA application identified by applicationId.

For getting 2FA application(s) you should use the HTTP GET method and the base URL with following end point:

End point for all applications: /1/applications
End point for one application: /1/applications/{applicationId}

Header field	Description
Authorization	Required. Basic + Base64(username:password).
Content-type	Required. The content type of the request body: `application/json`

Request path parameters

Parameters	Type	Description
applicationId	String	2FA application ID that you want to get.

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain received application object in JSON format.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to get the application(s) when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Response body parameters

Parameter	Type	Description
applicationId	String	2FA application ID.
name	String	2FA application name.
enabled	Boolean	Indicates if the created application is enabled.
processId	String	Process tracking ID. You can track conversion rate across 2FA process using multiple parameters (find more information here).
configuration	ApplicationConfiguration	Created 2FA application configuration.

ApplicationConfiguration

Parameter	Type	Description
pinTimeToLive	Long	Optional. PIN time to live (in millis). Default value: 900.000 milliseconds (15 minutes)
pinAttempts	Integer	Optional. Number of possible PIN attempts. Default value: 10
verificationAttempts	Integer	Optional. Number of PIN verification requests from one phone number (MSISDN) in a defined verification time interval. Default value: 1
verificationIntervalLength	Long	Optional. Verification time interval (in millis). Default value: 3.000 milliseconds (3 seconds)
initiationAttempts	Integer	Optional. Number of requests for generating a PIN and sending an SMS to one phone number (MSISDN) in a defined time interval. Default value: 3
initiationIntervalLength	Long	Optional. Time interval in which a defined number of initiation attempts for one phone number (MSISDN) can be realized. Default value: 86.400.000 milliseconds (1 day)

Note:
Find out more about Application configuration details here.

Example: Get all 2FA applications

Request

GET /2fa/1/applications HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic RkTpGSVR0lUdGVhbZWFt
Content-Type: application/json

Response

[
 {
  "applicationId": "8F0792F86035A9F4290821F1EE6BC06A",
  "name": "Test application 1",
  "processId": "9C815F8AF33282A7C6D48F9FE5FA2B67",
  "enabled": true,
  "configuration": {
   "pinTimeToLive": 1800000,
   "pinAttempts": 5,
   "verificationAttempts": 2,
   "verificationIntervalLength": 10000,
   "initiationAttempts": 5,
   "initiationIntervalLength": 1800000,
   "overallInitiationAttempts": 10000,
   "overallInitiationIntervalLength": 86400000
  }
 },
 {
  "applicationId": "9C815F8AF33282A7C6D48F9FE5FA2B67",
  "name": "Test application 2",
  "processId": "8F0792F86035A9F4290821F1EE6BC06A",
  "enabled": true,
  "configuration": {
   "pinTimeToLive": 3200000,
   "pinAttempts": 3,
   "verificationAttempts": 4,
   "verificationIntervalLength": 10000,
   "initiationAttempts": 5,
   "initiationIntervalLength": 1000000,
   "overallInitiationAttempts": 50000,
   "overallInitiationIntervalLength": 864000000
  }
 }
]

Example - Get 2FA application by `applicationId`

Request

GET /2fa/1/applications/8F0792F86035A9F4290821F1EE6BC06A HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic RkTpGSVR0lUdGVhbZWFt
Content-Type: application/json

Response

{
    "applicationId": "8F0792F86035A9F4290821F1EE6BC06A",
    "name": "Test application 1",
    "processId": "9C815F8AF33282A7C6D48F9FE5FA2B67",
    "enabled": true,
    "configuration": {
        "pinTimeToLive": 1800000,
        "pinAttempts": 5,
        "verificationAttempts": 2,
        "verificationIntervalLength": 10000,
        "initiationAttempts": 5,
        "initiationIntervalLength": 1800000,
        "overallInitiationAttempts": 10000,
        "overallInitiationIntervalLength": 86400000
    }
}

Create a message

This method allows you to create 2FA message for specific application.

For creating a 2FA message you should use the HTTP POST method and the base URL with following end point:

End point: /1/applications/{applicationId}/messages

Header field	Description
Authorization	Required. Basic + Base64(username:password).
Content-type	Required. The content type of the request body: `application/json`

Request path parameters

Parameters	Type	Description
applicationId	String	Required. 2FA application ID for which the message will be created.

Request body parameters

Parameters	Type	Description
pinType	String	Required. Type of PIN code that will be generated and sent as part of 2FA message. You can set PIN type to numeric, alpha, alphanumeric or hex so parameter must have one of these values: 1. NUMERIC 2. ALPHA 3. ALPHANUMERIC 4. HEX
pinPlaceholder	String	Required. PIN placeholder. This value should be part of a message text and it will be replaced with generated PIN code.
messageText	String	Required. Text of a message that will be sent. Message text should contain PIN placeholder.
pinLength	Integer	Required. PIN code length. PIN code length should be between 1 and 8 characters.
sender	String	Required. The name that will appear as the sender of the 2FA message (Example: CompanyName).

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain created message object in JSON format.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to create a massage when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Message response body parameters

Parameter	Type	Description
messageId	String	2FA message ID.
applicationId	String	2FA application ID for which the message was created.
pinPlaceholder	String	PIN code placeholder. Right before sending SMS, PIN code placeholder will be replaced with generated PIN code.
messageText	String	Text of a message that will be sent.
pinLength	Integer	PIN code length.
pinType	String	Type of PIN code that will be generated and sent as part of 2FA message.
sender	String	The name that will appear as the sender of the 2FA message (Example: CompanyName).

Example

Request

POST /2fa/1/applications/8F0792F86035A9F4290821F1EE6BC06A/messages HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic RkTpGSVR0lUdGVhbZWFt
Content-Type: application/json

{
  "pinType":"NUMERIC",
  "pinPlaceholder":"<pin>",
  "messageText":"Your pin is <pin>",
  "pinLength":4,
  "sender":"Infobip 2FA"
}

Response

{
 "messageId": "F66D67327326FCCB027BEAA916B94542",
 "applicationId": "8F0792F86035A9F4290821F1EE6BC06A",
 "pinPlaceholder": "<pin>",
 "messageText": "Your pin is <pin>",
 "pinLength": 4,
 "pinType": "NUMERIC",
 "sender": "Infobip 2FA"
}

Update a message

This method allows you to update 2FA message for specific application.

For updating a 2FA message you should use the HTTP PUT method and the base URL with following end point:

End point: /1/applications/{applicationId}/messages/{messageId}

Header field	Description
Authorization	Required. Basic + Base64(username:password).
Content-type	Required. The content type of the request body: `application/json`

Request path parameters

Parameters	Type	Description
applicationId	String	Required. 2FA application ID for which the message will be updated.
messageId	String	Required. Requested message ID.

Request body parameters

Parameters	Type	Description
pinType	String	Optional. Type of PIN code that will be generated and sent as part of 2FA message. You can set PIN type to numeric, alpha, alphanumeric or hex.
pinPlaceholder	String	Optional. PIN placeholder. This value should be part of a message text and it will be replaced with generated PIN code.
messageText	String	Optional. Text of a message that will be sent. Message text should contain PIN placeholder.
pinLength	Integer	Optional. PIN code length. PIN code length should be between 1 and 8 characters.
sender	String	Optional. The name that will appear as the sender of the 2FA message (Example: CompanyName).

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain updated message object in JSON format.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to update a massage when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Response body parameters

Parameter	Type	Description
messageId	String	2FA message ID.
applicationId	String	2FA application ID for which the message was created.
pinPlaceholder	String	PIN code placeholder. Right before sending SMS, PIN code placeholder will be replaced with generated PIN code.
messageText	String	Text of a message that will be sent.
pinLength	Integer	PIN code length.
pinType	String	Type of PIN code that will be generated and sent as part of 2FA message.
sender	String	The name that will appear as the sender of the 2FA message (Example: CompanyName).

Example

Request

All body parameters are optional, so only provided parameters will be updated.

PUT /2fa/1/applications/8F0792F86035A/messages/F66D67327326FCC HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic RkTpGSVR0lUdGVhbZWFt
Content-Type: application/json

{
  "pinType":"ALPHANUMERIC",
  "pinLength":6
}

Response

{
 "messageId": "F66D67327326FCC",
 "applicationId": "8F0792F86035A",
 "pinPlaceholder": "<pin>",
 "messageText": "Your pin is <pin>",
 "pinLength": 6,
 "pinType": "ALPHANUMERIC",
 "sender": "Infobip 2FA"
}

Get message(s)

This method allows you to get all 2FA messages for specific application. Also, you can get just one 2FA message identified by messageId.

For getting 2FA message(s) you should use the HTTP GET method and the base URL with following end point:

End point for all messages: /1/applications/{applicationId}/messages
End point for one message: /1/applications/{applicationId}/messages/{messageId}

Header field	Description
Authorization	Required. Basic + Base64(username:password).
Content-type	Required. The content type of the request body: `application/json`

Request path parameter

Parameters	Type	Description
applicationId	String	2FA application ID for which you want to get messages.
messageId	String	Message ID that you want to get.

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain received message object in JSON format.

Response body parameters

Parameter	Type	Description
messageId	String	2FA message ID.
applicationId	String	2FA application ID for which the message was created.
pinPlaceholder	String	PIN code placeholder. Right before sending SMS, PIN code placeholder will be replaced with generated PIN code.
messageText	String	Text of a message that will be sent.
pinLength	Integer	PIN code length.
pinType	String	Type of PIN code that will be generated and sent as part of 2FA message.
sender	String	The name that will appear as the sender of the 2FA message (Example: CompanyName).

Example - Get all messages for specific application

Request

GET /2fa/1/applications/8F0792F86035A/messages HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic RkTpGSVR0lUdGVhbZWFt
Content-Type: application/json

Response

[
 {
  "messageId": "9C815F8AF3328",
  "applicationId": "8F0792F86035A",
  "pinPlaceholder": "<pin>",
  "messageText": "Your PIN is <pin>.",
  "pinLength": 4,
  "pinType": "NUMERIC"
 },
 {
  "messageId": "8F0792F86035A",
  "applicationId": "8F0792F86035A",
  "pinPlaceholder": "<<>>",
  "messageText": "Your PIN is <<>>.",
  "pinLength": 6,
  "pinType": "HEXA"
 }
]

Example - Get one message by `applicationId` and `messageId`

Request

GET /2fa/1/applications/8F0792F86035A/messages/F66D67327326FCC HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic RkTpGSVR0lUdGVhbZWFt
Content-Type: application/json

Response

{
 "messageId": "F66D67327326FCC",
 "applicationId": "8F0792F86035A",
 "pinPlaceholder": "<pin>",
 "messageText": "Your pin is <pin>",
 "pinLength": 6,
 "pinType": "ALPHANUMERIC",
 "sender": "Infobip 2FA"
}

Generate an API key

This method allows you to generate an API key your account. You have to be authorized over API key in order to use all Client side methods:

Send a PIN
Verify a PIN
Resend a PIN
Get PIN status
Check is MSISDN verified

For generating an API key you should use the HTTP POST method and the base URL with following end point:

End point: /1/api-key

Header field	Description
Authorization	Required. Basic + Base64(username:password).
Content-type	Required. The content type of the request body: `application/json`

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain created API key.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to generate an API key when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Parameter	Type	Description
api-key	String	API key used for authorization in Client side methods.

Example

Request

POST /2fa/1/api-key HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic RkTpGSVR0lUdGVhbZWFt
Content-Type: application/json

Response

"003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9"

Send a PIN

This method allows you to generate and send a PIN over 2FA message to provided phone number.

For sending a PIN to provided phone number you should use the HTTP POST method and the base URL with following end point:

End point: /1/pin

Header field	Description
Authorization	Required. A valid API key for your account. If you don’t have an API key, you can create one using a Generate API key method. When you receive your API key, you should put it in the header after the authorization method and space i.e. `"App "`.
Content-type	Required. The content type of the request body: `application/json`

Request query parameters

Parameter	Type	Description
ncNeeded	Boolean	Optional. Indicates if Number Context needed before sending 2FA message. If `ncNeeded` value is `true`, Number Context will be sent before sending SMS. If `ncNeeded` value is `false`, SMS will be sent without sending Number Context. Default value: `true`.

Request body parameters

Parameter	Type	Description
applicationId	String	Required. 2FA application ID.
messageId	String	Required. 2FA message that will be sent to a phone number (MSISDN).
to	String	Required. Phone number (MSISDN) to which 2FA message will be sent. Must be in international format (Example: 41793026727).
from	String	Optional. Sender ID in numeric or alphanumeric format. If this parameter is not set, it will be automatically filled form the created message parameter `sender`.

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain sent PIN response in JSON format.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to send a PIN when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Send a PIN response

Parameter	Type	Description
to	String	Phone number (MSISDN) to which 2FA message was sent.
ncStatus	String	Status of sent Number Context. Number Context status can have one of the following values: NC_DESTINATION_UNKNOWN NC_DESTINATION_REACHABLE NC_DESTINATION_NOT_REACHABLE NC_NOT_CONFIGURED. If you get `NC_NOT_CONFIGURED` status, you should contact your account manager for configuring it. SMS will not be sent only if Number Context status is `NC_NOT_REACHABLE`.
smsStatus	String	Sent SMS status. SMS status can have one of the following values: MESSAGE_SENT MESSAGE_NOT_SENT.
pinId	String	Sent PIN code ID.

Example

Request

POST /2fa/1/pin HTTP/1.1
Host: oneapi.infobip.com
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Content-Type: application/json

{
  "applicationId":"6D48F9FE5FA2B679C815F8AF33282A7C",
  "messageId":"1036B771ACA7EC408772F93BC855D00A",
  "to":"41793026727"
}

Response

{
 "to": "41793026727",
 "ncStatus": "NC_DESTINATION_REACHABLE",
 "smsStatus": "MESSAGE_SENT",
 "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67"
}

Verify a PIN

This method allows you to verify received PIN over 2FA message.

For verifying a received PIN you should use the HTTP POST method and the base URL with following end point:

End point: /1/pin/{pinId}/verify

Header field	Description
Authorization	Required. A valid API key for your account. If you don’t have an API key, you can create one using a Generate API key method. When you receive your API key, you should put it in the header after the authorization method and space i.e. `"App "`.
Content-type	Required. The content type of the request body: `application/json`

Request path parameters

Parameter	Type	Description
pinId	String	Required. ID of the PIN code that has to be verified.

Request body parameters

Parameter	Type	Description
pin	String	Required. PIN code received by user.

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain Verify PIN response in JSON format.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to verify PIN when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Verify PIN response

Parameter	Type	Description
pinId	String	Sent PIN code ID.
msisdn	String	Phone number (MSISDN) to which 2FA message was be sent.
verified	Boolean	Indicates if the phone number (MSISDN) was successfully verified.
attemptsRemaining	Integer	Number of remaining PIN attempts.
pinError	String	Indicates if any error occurs during PIN verification. PIN error can have one of the following values: WRONG_PIN TTL_EXPIRED NO_MORE_PIN_ATTEMPTS

Example

Request

POST /2fa/1/pin/2B6792A7CFAC6D48F9AF3FE5328815F8/verify HTTP/1.1
Host: oneapi.infobip.com
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Content-Type: application/json

{
 "pin":"1598"
}

Response - correct PIN

{
 "pinId": "2B6792A7CFAC6D48F9AF3FE5328815F8",
 "msisdn": "41793026727",
 "verified": true,
 "attemptsRemaining": 0
}

Response - wrong PIN

{
 "pinId": "2B6792A7CFAC6D48F9AF3FE5328815F8",
 "msisdn": "41793026727",
    "verified": false,
    "attemptsRemaining": 2,
    "pinError": "WRONG_PIN"
}

Resend a PIN

This method allows you to resend already created PIN.

For resending a PIN to provided phone number you should use the HTTP POST method and the base URL with following end point:

End point: /1/pin/{pinId}/resend

Header field	Description
Authorization	Required. A valid API key for your account. If you don’t have an API key, you can create one using a Generate API key method. When you receive your API key, you should put it in the header after the authorization method and space i.e. `"App "`.
Content-type	Required. The content type of the request body: `application/json`

Request path parameters

Parameter	Type	Description
pinId	String	Required. ID of a PIN code that has to be resend.

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain Send PIN response in JSON format.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to resend a PIN when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Resend PIN response

Parameter	Type	Description
to	String	Phone number (MSISDN) to which 2FA message was sent.
ncStatus	String	Status of sent Number Context. Number Context status can have one of the following values: NC_DESTINATION_UNKNOWN NC_DESTINATION_REACHABLE NC_DESTINATION_NOT_REACHABLE NC_NOT_CONFIGURED. If you get `NC_NOT_CONFIGURED` status, you should contact your account manager for configuring it. SMS will not be sent only if Number Context status is `NC_NOT_REACHABLE`.
smsStatus	String	Sent SMS status. SMS status can have one of the following values: MESSAGE_SENT MESSAGE_NOT_SENT.
pinId	String	Sent PIN code ID.

Example

Request

POST /2fa/1/pin/2B6792A7CFAC6D48F9AF3FE5328815F8/resend HTTP/1.1
Host: oneapi.infobip.com
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Content-Type: application/json

Response

{
 "to": "41793026727",
 "ncStatus": "NC_DESTINATION_REACHABLE",
 "smsStatus": "MESSAGE_SENT",
 "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67"
}

Get PIN status

This method allows you to get delivery information about all sent 2FA messages for one PIN code.

For resending a PIN to provided phone number you should use the HTTP POST method and the base URL with following end point:

End point: /1/pin/{pinId}/status

Header field	Description
Authorization	Required. A valid API key for your account. If you don’t have an API key, you can create one using a Generate API key method. When you receive your API key, you should put it in the header after the authorization method and space i.e. `"App "`.
Content-type	Required. The content type of the request body: `application/json`

Request path parameters

Parameter	Type	Description
pinId	String	PIN code ID

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain Get PIN status response in JSON format.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to get PIN status when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Get PIN status response

Parameter	Type	Description
status	String	2FA message delivery status. Status can have one of the following values
description	String	2FA message delivery status description.
finalStatus	String	Indicates if 2FA message delivery status is final.

Status list

Value	Description	FinalStatus
`MESSAGE_ACCEPTED`	Message accepted	true
`MESSAGE_NOT_SENT`	Message not sent	false
`MESSAGE_NOT_DELIVERED`	Message sent, not delivered	true
`MESSAGE_WAITING_DELIVERY`	Message sent, waiting for delivery	false
`MESSAGE_DELIVERED`	Message sent and delivered	true
`MESSAGE_NETWORK_NOT_ALLOWED`	Message not sent, network not allowed	true
`MESSAGE_NETWORK_NOT_AVAILABLE`	Message not sent, bulk or gateway offline	true
`MESSAGE_INVALID_DESTINATION_ADDRESS`	Message not sent, invalid destination address	true
`MESSAGE_DELIVERY_UNKNOWN`	Message delivery unknown	true
`INVALID_SOURCE_ADDRESS`	Message not sent, invalid source address	true
`NOT_ENOUGH_CREDITS`	Message not sent, not enough credits	true
`MESSAGE_REJECTED`	Message rejected	true
`MESSAGE_EXPIRED`	Message expired	true
`SYSTEM_ERROR`	System error	true

Example

Request

GET /2fa/1/pin/2B6792A7CFAC6D48F9AF3FE5328815F8/status HTTP/1.1
Host: oneapi.infobip.com
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Content-Type: application/json

Response

[
 {
  "status": "MESSAGE_DELIVERED",
  "description": "Message sent and delivered",
  "finalStatus": true
    },
    {
  "status": "MESSAGE_WAITING_DELIVERY",
  "description": "Message sent, waiting for delivery",
  "finalStatus": false
    }
]

Check is MSISDN verified

This method allows you to check if the phone number (MSISDN) is verified for specific 2FA application .

For resending a PIN to provided phone number you should use the HTTP POST method and the base URL with following end point:

End point: /1/applications/{applicationId}/verifications

Header field	Description
Authorization	Required. A valid API key for your account. If you don’t have an API key, you can create one using a Generate API key method. When you receive your API key, you should put it in the header after the authorization method and space i.e. `"App "`.
Content-type	Required. The content type of the request body: `application/json`

Request query parameters

Parameter	Type	Description
msisdn	String	Optional. Filter by phone number (MSISDN).
verified	Boolean	Optional. Filter by verified (true or false).
sent	Boolean	Optional. Filter by message sent status (true or false).

Response Format

On success, response header HTTP status code will be 200 OK and the body will contain Check verification status response in JSON format.

On error, you will receive an error response status code in the header and the response body will contain an error object. If you try to check MSISDN verification status when you do not have the user’s authorization, you will receive an error 401 Unauthorized.

Check verification status response

Parameter	Type	Description
msisdn	String	Phone number (MSISDN) for which verification status is checked.
verified	Boolean	Indicates if the phone number (MSISDN) is already verified for 2FA application with given ID.
verifiedAt	Long	Verification UNIX timestamp (in millis), if the phone number (MSISDN) is verified.
sentAt	Long	Sent UNIX timestamp (in millis), if the phone number (MSISDN) is verified.

Example

Request

GET https://oneapi.infobip.com/2fa/1/applications/{applicationId}/verified?msisdn="41793026727" HTTP/1.1
Host: oneapi.infobip.com
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Content-Type: application/json

Response

[
 {
  "msisdn": "41793026727",
  "verified": true,
  "verifiedAt": 1418364366,
  "sentAt": 1418364246
    }
]

Response Status Codes

Status Code	Description
200	OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.
400	Bad Request - The request could not be understood by the server due to malformed syntax or invalid argument.
401	Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.
404	Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition.
429	Too Many Requests - Rate limiting has been applied.
500	Internal Server Error.
503	Service Unavailable - The server is currently unable to handle the request due to a temporary condition which will be alleviated after some delay. You can choose to resend the request again.

Error Details

Apart from the response code, unsuccessful responses return information about the error as an error JSON object:

Error object

Parameter	Type	Description
messageId	String	ID of an error
text	String	A short description of the error.

Error example

Here, as an example, is the error that occurs when trying to send PIN with non-existent message:

Request

    POST /2fa/1/pin HTTP/1.1
    Host: oneapi.infobip.com
    Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
    Content-Type: application/json

    {
      "applicationId":"E56D48F9FFA2B679C815F8AF33282A7C",
      "messageId":"CA71036B771AEC408772F93BC855D00A",
      "to":"385985555555"
    }

Response

{
    "requestError": {
        "serviceException": {
            "messageId": "RESOURCE_NOT_FOUND",
            "text": "Application or message with given ID cannot be found."
        }
    }
}

Infobip 2-factor authentication HTTP API

Base URL

Authorization

Basic authorization

API key authorization

Step by step integration

Application configuration details

PIN Time To Live

PIN Attempts

Verification Attempts

Verification Interval Length

Initiation Attempts

Initiation Interval Length

API endpoint reference list

Service configuration

Application

Message

API key

Client side methods

PIN

Verifications

API methods usage

Create application

Request body parameters

ApplicationConfiguration

Response format

Application response body parameters

Example

Basic request (required parameters only)

Response

Advanced Request

Response

Update application

Request path parameters

Request body parameters

ApplicationConfiguration

Response Format

Response body parameters

Example

Request

Response

Get application(s)

Request path parameters

Response Format

Response body parameters

ApplicationConfiguration

Example: Get all 2FA applications

Request

Response

Example - Get 2FA application by applicationId

Request

Response

Create a message

Request path parameters

Request body parameters

Response Format

Message response body parameters

Example

Request

Response

Update a message

Request path parameters

Request body parameters

Response Format

Response body parameters

Example

Request

Response

Get message(s)

Request path parameter

Response Format

Response body parameters

Example - Get all messages for specific application

Request

Response

Example - Get one message by applicationId and messageId

Request

Response

Generate an API key

Response Format

Example - Get 2FA application by `applicationId`

Example - Get one message by `applicationId` and `messageId`