2-factor authentication

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

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

The Authorization header is constructed as follows:

  1. Username and password are combined into a string username:password.
  2. The resulting string is encoded using the RFC2045-MIME variant of Base64.
  3. 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

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

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

PIN

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.

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

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