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/rejected/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’, ‘rejected’ 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, "message": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "message": "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
POST jwt 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)

jwt

jwt (optional) this value is available in cookies if the website uses eGuardian DBFP javascript file, for more details see the section 9.


Response

Status Response
200 {

"channel":        ‘<channel>’,

"status":            ‘pending/approved/rejected/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’, ‘rejected’ 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, "message": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "message": "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/rejected/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, rejected, expired, pending.

device_id (string) - unique device identifier of the device that user has used to reply to an authentication request.
403 {"success": false, "message": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "message": "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://chart.apis.google.com/chart?cht=qr&chs=220x220&chl=" + qrcode + "#&chld=H|0";
      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, "message": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "message": "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, "message": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "message": "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, rejected, 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, "message": "Invalid uid and secret combination, Application not found!"}
401 {"success": false, "message": "Email address provided is not a valid registered Acceptto account!"}

8. Calculate LOA Score (Risk Engine)

If the Relying party organization and application has access to standalone risk engine license, the Relying party can submit the raw request information to eGuardian® API in order to calculate the LOA score for the current session. LOA stands for Level of assurance, which is a score that shows how strong is the level of user’s authentication score. This score is calculated based on history and normality of user behavior and various real-time factors that are present in the request context.

This API can be used for continuous authentication to decrease or increase the LOA score based on the changes to the session and request context. For example, a change in IP address or browser fingerprint or GPS location of the user can have an impact in the current session’s LOA score.

Request

Method URL
POST api/v9/risk_engine/calculate_score

Type Params Values
POST session_uid string
POST event string
POST user_uid string
POST context object
POST uid string
POST secret string

session_uid

session_uid Unique identifier for the session. This is the unique value that relying party should generate for life time of a session. session_uid should be unique across relying party organization between different applications.

event

event authentication event, possible values are pre-auth, auth, post-auth, cont-auth (Continuous authentication).

user_uid

user_uid unique user identifier. user_uid should be unique across relying party organization between different applications. This value can be null during pre-auth event. Server will return list of possible users during pre-auth phase.

context

context context of authentication request which should contain all the key/values relying party has from user’s request. Depending on the keys present in this parameter, eGuardian® risk engine decides which risk analyzers needs to be engaged in calculating the final LOA score. Sample context keys: ip_address, hash1, hash2, hash3, hash4, fingerprint, latitude, longitude, auth_method. hash1, hash2, hash3, hash4, and fingerprint are calculated using eGuardian® DBFP javascript plugin. Possible values for auth_method are: password, push, totp, sms, email, voice. auth_method can contain more than one auth_method separated by comma. e.g “password, totp”.

uid

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

secret

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


Sample Request

POST /api/v10/risk_engine/calculate_score HTTP/1.1
Host: https://mfa.acceptto.com
Content-Type: application/json

{ "uid":"148907487408fb703a79fe63c967f7120da0fe92b5b2a2c43c303524533f19", "secret": "456712afa152450653d7387d8f42698bfa3557f0d9e791a83231d0a8aec6f69d70", "user_uid":"user-f97fe76cb378eef2337fc2be3da85a8a", "event": "post-auth", "context": {"ip_address":"74.50.231.26", "latitude": "49.3199", "longitude": "-123.099", "hash1": "4b7c7aae4570ad50c7f944f4e4af797a", "hash2": "12cc7a4d46289fe698e60e398fb6b840", "hash3": "471611d87dd8fd294ca3f2525ba68ee8", "hash4": "d932de90b8330a6d2f5e2101c7439fff", "fingerprint": "11611f90ecbe1b050bdc88812a50e722", "auth_method": "totp", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0.3 Safari/605.1.15" }


Response Format and Examples

Status Response
200 {"success":true, "loa_score": 3.5, "message":""}

success (boolean) - whether call to risk engine was successful or not.

loa_score (float) - Calculated LOA score by risk engine based on the parameters provided in the request context. Reason behind the LOA score given to session is available in relying party dashboard for organization admin.

message (string) - if any error happened and success parameter was false error message is returned in message.
401 {"success": false, "loa_score": 0, "message": "Risk Engine APIs are not enabled for this application. please contact support@acceptto.com for more information."}
403 {"success": false, "loa_score": 0, "message": "Invalid uid and secret combination, Application not found!"}

9. MFA integration with DBFP

Add the DBFP javascript file right before the closing body tag of your HTML page:


  <!-- eGuardian(r)  DBFP -->
  <script type="text/javascript" src="https://dbfp.acceptto.com/bfp.js"></script>
  <!-- End eGuardian(r)  DBFP -->

This script will set a cookie named jwt that you can pass as a parameter to authenticate_with_options API. This parameter contains a value that the server uses to assess the risk of authentication request including browser fingerprint, IP address of user and GPS location of the user’s browser. The server compares this data with the history of user behavior data to detect anomalies.

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