OneSpan Developer: Events Validation Endpoint

Securing non-monetary events is crucial for the business integrity in any organization. Through Events/Validate endpoint, OneSpan Intelligent Adaptive Authentication (IAA) receives non-monetary events triggered in a user application. Risk Analytics (RA) will then assess the ethnicity of these events and prompt the end-user to provide the appropriate authentication method, depending on the risk associated with an event. In this blog, we will illustrate non-monetary events’ validation using the Sandbox Interactive API and show the possible RA responses to an event. 

Before We Begin

Prior to exploring the Events Validation endpoint, you must first be a OneSpan Community member and sign up for a free Intelligent Adaptive Authentication sandbox account. Here are step-by-step instructions on how to do so.

You should also be sure to have at least one registered user prior to trying this call. To learn how to register a user, check out this detailed user’s registration blog.

Endpoint URL

The request URL for this API call will resemble the example below:

https://{your_tenant_ID}.sdb.tid.onespan.cloud/v1/users/{userID@domain}/events/validate

You won’t need to provide this URL during the tutorial. It is only to show the structure of the URL. The URL will be automatically assigned in the Interactive API when calling the web service. 

Try It Out

In order to experiment with the Events Validation API, navigate to the IAA Sandbox Interactive API document in your OneSpan Community account. In the Open API Swagger editor, expand the “Events” resource. You will then find an entry for the Events /Validate HTTP Post method as shown in the image below:  

URL Path Parameters:

For the purpose of the Events/Validate API call, there is a required path parameter for the unique user identifier. It will be formatted as userID@domain. An example of the userID is “iaa_user”. It is the userID that has been activated on the trusted device. The portion of the parameter following the “@” sign is the user domain. This entry should be replaced with the “Sandbox User” string shown below, which is present in your Sandbox details section under the “Intelligent Adaptive Authentication” tab of your Sandbox homepage.

Events Validation Request Body

Note: Events validate API is specific to the OneSpan Intelligent Adaptive Authentication solution. Its purpose is to notify Risk Analytics of an event and transmit the necessary data to make a unique decision concerning the event. For this reason, it is not required to select an object type in the request body of the RESTful call, as it was the case for API calls in previous blogs. 

The request body will look like the example below of the Events/Validate endpoint’s required fields.

{
  "eventType": "LoginSuccess",

  "relationshipRef": "iaa_enduser",

  "sessionID": "4ed23ea44f23",

  "cddc": {

    "browserCDDC": {

      "fingerprintRaw": "{browser:{\"userAgent\":Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36},support:{\"ajax\":true,\"boxModel\":undefined,\"changeBubbles\":undefined,\"checkClone\":true,\"checkOn\":true,\"cors\":true,\"cssFloat\":undefined,\"hrefNormalized\":undefined,\"htmlSerialize\":undefined,\"leadingWhitespace\":undefined,\"noCloneChecked\":true,\"noCloneEvent\":undefined,\"opacity\":undefined,\"optDisabled\":undefined,\"style\":undefined,\"submitBubbles\":undefined,\"tbody\":undefined},computer:{\"screenWidth\":2560,\"screenHeight\":1440,\"OS\":\"Microsoft Windows\",\"platform\":\"Win32\"},additional:{}}",

      "fingerprintHash": "e96dadc9651f5fe8f071110eb174fe8e7a17a9d7a96b3b1980c13e5b4af3a4d7"

    }

  },

  "clientIP": "192.168.0.1"

}

Request Payload

It contains the mandatory JSON objects shown in the table:

Calling the Endpoint

Now we are ready to make a RESTful call to the Events/Validate endpoint using the IAA interactive Sandbox API. To make the call, click on the “Try it out” button shown in the screenshot below and located to the right of the HTTP POST method section. Once requested, you will receive the response body back in a JSON format. It will be similar to the response payload described in the following section.

Response Payload

Below is an example of the returned response body with a 200 response code which indicates a successful request.

{

  "requestID": "413b2c39-2d67-4293-9adb-25601731b062",

  "riskResponseCode": 0,

  "sessionStatus": "accepted",

  "requestMessage": "0000F8B81D"

}

Response Body Fields’ Description

The “requestID” is the first field in the response. It is a string of 36 characters used to keep a reference of the preceding API call. This ID could be useful for debugging and referencing.

The “riskResponseCode” field is the response code from Risk Analytics. The value “0” in the response above indicates that the request was accepted and the user had been authenticated successfully without any extra measures required. The response type to the various activities could be detected from Risk Analytics.

Below is a list of other possible values that can be returned by Risk Analytics. Also, additional values can be configured through the Risk Analytics Presentation Service.

The “sessionStatus" field in the JSON response represents the current status of the session after the request has been sent. The table below lists the possible status values:

The "requestMessage" field is of type String. It is used to transmit an orchestration command to the end user trusted device.

Today, we covered how to make a non-monetary event through the OneSpan Interactive API. In the next blog, we will demonstrate how to create a Risk Analytics rule for non-monetary events. Meanwhile, if you have any question, please reach out on the OneSpan Community Portal Forums.

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today