Acceptto MFA REST API

1. Authenticate

Sends an authentication request to the user and obtains the authentication channel, this channel can be used for checking the authentication result later.

After getting the authentication channel in this step, the relying party should save the channel in a session and redirect users to the”Select Your Authenticator” MFA page:

https://mfa.acceptto.com/mfa/index?channel=channel_received_in_response_of_authenticate&callback_url=https://yourdomain.com/auth/mfa_callback

This page allows the user to choose their second-factor authentication method. Based on the policies defined by relying party user has the option of using Push Notification, Text Message, Voice Call, TOTP for replying to the authentication request. As soon as users select “Accept” or “Decline” with the push, or verifies with a one-time passcode, they will get redirected back to callback_url that was passed by the relying party.

The relying party should #check the result of authentication on callback page to see if it got approved or rejected by the user.

Request

Method URL
POST api/v9/authenticate

Type Params Values
POST uid string
POST secret string
POST email string
POST message string
POST timeout string
POST totp string



uid

uid of the application. When an organization creates an application in eGuardian® dashboard this uid gets generated.

secret

secret of the application. When an organization creates an application in eGuardian® dashboard this secret gets generated.

email

email address of the user, which the relying party wants to authenticate.

message

message to deliver to the user. This message gets delivered to the user device via push notification. e.g “Would you like to sign into Website X?”

timeout

timeout value for the authentication request is in seconds. If the user doesn’t respond in the specified time period, an authentication request expires. The max value is 600 seconds. Setting the value any higher will cause it to revert back to 600 seconds.

totp

totp (optional) The relying party can authenticate users using TOTP by allowing them to enter their time based one-time passcodes while signing in. When TOTP is specified and is correct the status of response will become approved. TOTP is a six-digit passcode that changes every 30 seconds. (https://tools.ietf.org/html/rfc6238)


Response

Status Response
200 {

"channel":        ‘<channel>’,

"status":            ‘pending/approved/declined/expired’,

"meta_data":    ‘meta data generated by eGuardian for authentication.’,

}

channel (string) - all further API calls related to this authentication request must have this channel.
status (string) - status of an authentication request. In case of an auto-accept, auto-reject policy match, status becomes ‘approved’, ‘declined’ immediately otherwise it should be ‘pending’. An empty or null status also means ‘pending’ for the user decision to approve/decline the authentication.
meta_data (key/value) - metadata can contain various information based on the context of authentication, for example, if the relying party has enabled eGuardian browser fingerprinting (BFP) it will contain the hash returned by DBFP. Or if a policy matched and authentication got auto-approved or auto-rejected it contains the information about the policy that matched.
403 {"success": false, "success": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "success": "Email address provided is not a valid registered Acceptto account!"}

2. Authenticate with options

This API is very similar to the authenticate API, the only difference is in the options that the relying party can pass and customize the authentication and notification method for end-user.

If relying party is not passing an auth_type parameter to this API it will behave like the #authenticate API and redirect users to the MFA/index page.

But if the relying party is choosing an auth_type notification method, the relying party has different options:

push_notification (auth_type=1): Relying party should show a waiting page to the user and use the method explained in “Getting notified about user action” to detect when it should call check API.

SMS or voice call (auth_type=2 or auth_type=3): If one of these options are chosen, the relying party should show a user interface to users to enter the passcodes that were sent to them using text message or voice call. After getting the passcode from the user, the relying party should use the #verify_one_time_password API to check if the passcode is correct.


Request

Method URL
POST api/v9/authenticate_with_options

Type Params Values
POST uid string
POST secret string
POST email string
POST message string
POST timeout string
POST auth_type string
POST type string
POST ip_address string
POST remote_ip_address string
POST rp_risk_percentage string
POST totp string



uid

uid of the application. When an organization creates an application in eGuardian® dashboard this uid gets generated.

secret

secret of the application. When an organization creates an application in eGuardian® dashboard this secret gets generated.

email

email address of the user, which the relying party wants to authenticate.

message

message to deliver to the user. This message gets delivered to the user device via push notification. e.g “Would you like to sign into Website X?”

timeout

timeout value for the authentication request is in seconds. If the user doesn’t respond in the specified time period, an authentication request expires. The max value is 600 seconds. Setting the value any higher will cause it to revert back to 600 seconds.

auth_type

auth_type (optional) method of notification for end-user. 1 is for push notification, 2 is a text message, 3 is a voice call.

type

type (optional) of the authentication, this will be shown on the mobile app to the end-user. e.g login, account management, transaction, …

ip_address

ip_address (optional) of the user, this can be used for policy-based risk assessment.

remote_ip_address

remote_ip_address (optional) of the user, this can be used for policy-based risk assessment.

rp_risk_percentage

rp_risk_percentage (optional) is the assessment of the risk of authentication from the relying party, based on the defined policies, eGuardian® will use this percentage to decide on auto-accept, auto-reject or force biometric authentication.

totp

totp (optional) The relying party can authenticate users using TOTP by allowing them to enter their time based one-time passcodes while signing in. When TOTP is specified and is correct the status of response will become approved. TOTP is a six-digit passcode that changes every 30 seconds. (https://tools.ietf.org/html/rfc6238)


Response

Status Response
200 {

"channel":        ‘<channel>’,

"status":            ‘pending/approved/declined/expired’,

"meta_data":    ‘meta data generated by eGuardian for authentication.’,

}

channel (string) - all further API calls related to this authentication request must have this channel.
status (string) - status of an authentication request. In case of an auto-accept, auto-reject policy match, status becomes ‘approved’, ‘declined’ immediately otherwise it should be ‘pending’. An empty or null status also means ‘pending’ for the user decision to approve/decline the authentication.
meta_data (key/value) - metadata can contain various information based on the context of authentication, for example, if the relying party has enabled eGuardian browser fingerprinting (BFP) it will contain the hash returned by DBFP. Or if a policy matched and authentication got auto-approved or auto-rejected it contains the information about the policy that matched.
403 {"success": false, "success": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "success": "Email address provided is not a valid registered Acceptto account!"}
3. Getting notified about the user action

After calling #authenticate_with_options with auth_type (Push Notification/SMS) the relying party has the option of getting notified as soon as a user replies to the authentication request either by approve or decline on the mobile app or replying to SMS with a passcode to approve the authorization.

In order to get notified the relying party should use the channel received in the response of #authenticate_with_options API to subscribe to eGuardian® Faye server with this javascript snippet (written using JQuery but simple javascript will work too).

<script src="https://faye.acceptto.com/faye/faye.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>

<script type="text/javascript">
   $(function() {
       var faye = new Faye.Client("https://faye.acceptto.com/faye");
       faye.subscribe("/messages/<%= @channel %>", function (data) {
           window.location.reload(); // refresh the page and call check api on refresh
       });
   });
</script>

As soon as the user approves or declines the authentication request the code block inside faye.subscribe is executed. Make sure that you are replacing the <%= @channel %> with the channel you got back from the #authenticate_with_options call and you should customize the code block inside faye.subscribe, the method above just refreshes the page, you can call #check API on page load to see the result of authentication.

4. Check authentication result

Uses channel to check the status of authentication.


Request

Method URL
POST api/v9/check

Type Params Values
POST channel string
POST email string
POST uid string
POST secret string



channel

channel channel returned in response of #authenticate or #authenticate_with_options calls.

email

email address of the user which the relying party wants to check the authentication result for.

uid

uid of the application. When an organization creates an application in eGuardian® dashboard this uid gets generated.

secret

secret of the application. When an organization creates an application in eGuardian® dashboard this secret gets generated.


Response

Status Response
200 {"status":"approved/declined/expired/pending/null", ""device_id":"yeirwadf12-Yhg"}

status (string) - status of the authentication request. Can be null or empty which means the user has not replied to authentication request yet and it’s pending. Other possible values are: approved, declined, expired, pending.

device_id (string) - unique device identifier of the device that user has used to reply to an authentication request.
403 {"success": false, "success": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "success": "Email address provided is not a valid registered Acceptto account!"}

5. Login with QR Code

The idea behind QR code login is instead of entering their username and password, users should be able to just scan a QR code, receive a push notification on their device, approve and sign in. Basically, it is a login without a single keystroke.

Using the javascript snippet below you will be able to generate and show an eGuardian® compatible QR code to users for Login:




<script src="https://faye.acceptto.com/faye/faye.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
<script type="text/javascript">

   $(function() {
      uid = "918dc48d7efa41516c37319bc85b8979ee2891aac01c0aba01c28ed6c33502b7"

      var faye = new Faye.Client("https://faye.acceptto.com/faye");
      hex1 = Math.floor(Math.random()*16777215).toString(16);
      hex2 = Math.floor(Math.random()*16777215).toString(16);
      var d = new Date();
      var time_since_epoch = d.getTime();
      var channel = time_since_epoch + hex1 + hex2;
      var qrcodeJSON = '{ "app_uid":"' + uid + '", "channel":"' + channel + '" }';
      var qrcode = window.btoa(qrcodeJSON);
      $('#login_qrcode').attr("src", "https://api.qrserver.com/v1/create-qr-code/?size=220x220&margin=0&data=" + qrcode);
      faye.subscribe("/messages/" + channel, function (data) { window.location.replace("https://yourdomain.com/qrcode/channel?channel=" + channel);
      });
  });
</script>

<center>
<img id="login_qrcode" alt="qrcode">
  </center>

In the Faye callback block, you need to replace the https://yourdomain.com/qrcode path with a path that your web application handles. On this controller you need to implement an API call and pass the channel to the eGuardian® API and get the corresponding user’s email address:


Request

Method URL
POST api/v9/get_user_by_websocket_channel

Type Params Values
URL_PARAM uid string
URL_PARAM secret string
URL_PARAM websocket_channel string



uid

uid of the application. When an organization creates an application in the eGuardian® dashboard this uid gets generated.

secret

secret of the application. When an organization creates an application in the eGuardian® dashboard this secret gets generated.

websocket_channel

websocket_channel generated by the javascript snippet above (channel).


Response

Status Response
200 {"success":"true", "message":"", "user_email:":"foo@bar.com"}

success (boolean) - shows whether the find matching user email address was successful or not.
message (string) - error message if success was false.
user_email (string) - email address of the user who scanned the QR code on the phone.
403 {"success": false, "success": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "success": "Email address provided is not a valid registered Acceptto account!"}

After getting a user’s email address, the relying party should call the #authenticate or #authenticate_with_options API and continue as if the user entered their username and password. Since users are scanning the QR codes using their trusted mobile devices on the It’sMe app, this process completely eliminates the friction of entering username and passwords.


6. Is User Valid?

Before using eGuardian® as an MFA provider, the relying party has the option of checking to see if the user is registered with eGuardian® and has a valid account.


Request

Method URL
POST api/v9/is_user_valid

Type Params Values
URL_PARAM email string
URL_PARAM uid string
URL_PARAM secret string



email

email address of the user of the relying party that wants to see if it exists on eGuardian®.

uid

uid of the application. When an organization creates an application in the eGuardian® dashboard this uid gets generated.

secret

secret of the application. When an organization creates an application in the eGuardian® dashboard this secret gets generated.


Response

Status Response
200 {"valid":true, "registration_state":"finished"}

valid (boolean) - returns true if user’s email address is registered and valid on eGuardian®.
registration_state (string) - returns current registration state of the user, could be one of these states: finished, waiting_for_email_confirm, waiting_for_mobile_confirm, waiting_for_security_questions. Anything other than finished means user signup process has not finished yet.
403 {"success": false, "success": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "success": "Email address provided is not a valid registered Acceptto account!"}

7. Verify One Time Password

As explained in #autenticate_with_options API section, If the relying party decided to implement its own “choose your authentication method” interface for the user, when the user chooses to use SMS or voice call for authentication, the relying party should show a textbox to the user to enter the one time password that the user received via phone call or SMS.

The relying party can use the otp_verify method to check if the one time password entered by the user is correct or not. The maximum retry attempts for a one time password is 3 times, after three unsuccessful attempts the authentication status becomes rejected.

Please note that one time passcodes are different with TOTPs (Time-based one time passwords) that users have in the It'sMeTM app.


Request

Method URL
POST api/v9/otp_verify

Type Params Values
URL_PARAM email string
URL_PARAM uid string
URL_PARAM secret string
URL_PARAM channel string
URL_PARAM otp string



email

email address of the user of the relying party that wants to see if it exists on eGuardian®.

uid

uid of the application. When an organization creates an application in the eGuardian® dashboard this uid gets generated.

secret

secret of the application. When an organization creates an application in the eGuardian® dashboard this secret gets generated.

channel

channel channel returned in response of #authenticate or #authenticate_with_options calls.

otp

otp sent to the user’s phone via phone call or SMS text message.


Response

Status Response
200 {"status":approved, "message":""}

status (string) - status of the authentication request. Can be null or empty which means the user has not replied to the authentication request yet and it’s pending. Other possible values are: approved, declined, expired, pending.
message (string) - if any error happened with verifying the one time password, return that error message. e.g. “Maximum PIN attempts exceeded. Authorization request denied.”
403 {"success": false, "success": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "success": "Email address provided is not a valid registered Acceptto account!"}

Conventions
  • Relying Party - Relying party is an organization or application which relies on Acceptto eGuardian® for doing multi-factor authentication.
  • Status - HTTP status code of the response.
  • All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued per request server.
  • All response is in JSON format.
  • All request parameters are mandatory unless explicitly marked as (optional)
  • The type of values accepted for a request parameter is shown in the values column like this [10|]. The | symbol means OR. If the parameter is (optional), the default value is shown in blue bold text, as 10 is written in [10|].

Status Codes

All status codes are standard HTTP status codes. The below ones are used in this API.

2XX - Success of some kind

4XX - Error occurred in the client’s part

5XX - Error occurred in the server’s part


Status Code Description
200 OK
400 Bad request
401 Authentication failure / Email or user not found
403 Invalid uid and secret / Forbidden
404 Resource not found
405 Method Not Allowed
409 Conflict
412 Precondition Failed
417 Expectation failed: No device paired for user’s account.
500 Internal Server Error
501 Not Implemented
503 Service Unavailable