OneSpan Developer: Intelligent Adaptive Authentication - User Unregister

OneSpan Intelligent Adaptive Authentication Sandbox API enables you to manage all the aspects associated with a user account. In the previous blog “OneSpan Developer: Intelligent Adaptive Authentication - User Registration” we demonstrated how to register a new user for OneSpan Intelligent Adaptive Authentication (IAA). In this article, we will explore the “User Unregister” endpoint, and show how easy it is to delete a user that has been previously registered. We will show how to construct the endpoint URL, a sample request body, and the possible response values for both the HTTP Post request and OneSpan Risk Analytics.

Before We Begin

Prior to exploring the User Unregister web service, 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.

Introduction

The User Unregister API allows you to delete an existing user account from the OneSpan Intelligent Adaptive Authentication server. If the user account deletion was successful, a 200-OK status code will be returned. In addition, you will also receive a Risk Response Code from Risk Analytics to indicate whether the unregistration was successful or whether an additional authentication is required to confirm the deletion of the indicated user account. A full list of the expected Risk Response Codes will be described later in the tutorial. In addition, if the request was not successful for any reason, an HTTP error response code will be returned with a meaningful message. This message will help explain the cause of the  error and make it easier to debug it.

Example of the Structure of the User Registration API 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}/unregister

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

Navigate to the User Unregister Interactive API:

In order to experiment with the user unregister API, there must first be a user that has already been registered on the system. Navigate to the IAA Interactive Sandbox API of your OneSpan Community account. In the OpenAPI Swagger editor, expand the “Users” resource. You will then find an entry for the User Unregister HTTP Post method as shown in the image below.  

URL Path Parameters:

For the purpose of the User Unregister 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 chosen previously when registering the user account that has now being deleted. 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.

User Unregister API Request Body:

Under the “Request Body” section of User Unregister endpoint, select "AdaptiveUnregisterUserInput" object type from the dropped down menu as shown below. This object type is used to delete the user selected in the path parameter. You will then get an example of the JSON payload to unregister a user. It will be populated with a sample of the JSON objects which are required by the API of the " AdaptiveUnregisterUserInput" object type. 

The request body will look like the example below of the “users/unregister” endpoint’s required fields.

Request Payload

{
  "objectType": "AdaptiveUnregisterUserInput",

  "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",

  "relationshipRef": "userid33",

  "sessionID": "4ED23EA44F23"

}

Request Payload’s Required Fields’ Description

Calling the User Unregister Endpoint

At this point, we are ready to make the REST call to unregister the specified user using the IAA interactive Sandbox API. To call the endpoint, click on the “Try it out” button shown in the screenshot below and located to the right of the “/users/unregister” 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.

User Unregister API Call Response Body

Below is an example of returned response body of a successful “/users/unregister” API call.

{
  "riskResponseCode": 0
}

“riskResponseCode” 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 deleted from the system. Below is a list of values that can be returned by Risk Analytics. Also, additional values can be configured through the Risk Analytics Presentation Service.

HTTP Response Status Codes

The table below shows the expected response codes when attempting to delete a user account

In this blog, we demonstrated how to unregister a new user using the IAA Sandbox Interactive API. We also explored the structure and examples of the request and the response payloads, which are required by the “/users/unregister” endpoint. Then we concluded with describing the expected Risk response code, and the HTTP status codes for the User Unregister API. Through this tutorial, you can keep your user list tidy and ensure there are no lingering accounts left unused. If you have any questions regarding this tutorial, feel free to reach us on the OneSpan Community Portal Forums.

Check out more of the Users’ category endpoints:

• User Register Endpoint
• Users Query Endpoint
• User Update Endpoint

OneSpan Developer Community

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

Join Today