OneSpan Developer: Intelligent Adaptive Authentication — Users Query Endpoint

OneSpan Intelligent Adaptive Authentication (IAA) provides an easy way to list the users that have been registered for a specific domain. With the User Query endpoint, you can gain insight into each of your currently registered users within your sandbox account. There are various parameters that allow you to conveniently query only specific users or to paginate through multiple instances. In this blog, we will take a look at the User Query endpoint, its path parameter options, and how you can test it out from the IAA Sandbox Interactive API.

Before We Begin: Join the OneSpan Developer Community

Prior to exploring the users' query 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.

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 OneSpan Developer: Intelligent Adaptive Authentication - User Registration.

Endpoint URL

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

https://{your_tenant_ID}.sdb.tid.onespan.cloud/v1/users

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

Try It with the Interactive API Doc

In order to experiment with the Users Query API, navigate to the IAA Sandbox Interactive API document of your OneSpan Community account. In the Open API Swagger editor, expand the “Users” resource. You will then find an entry for the Users Query HTTP Get method as in the image below:  

 
The Users Query API is fairly straightforward to use. There is no requirement to provide a JSON request body for the HTTP GET method call. All you need is to set up the path parameters explained below to tailor the call for specific results.

URL Parameters  

The table below shows the various path parameter options that are used to customize the query within the Sandbox Platform API. It also includes the description and example of each path parameter to help you make the best use of the User Query endpoint.

Below is a simple example of what the Request URL will look like with some of the parameters added:

https://ospanuser-mail.sdb.tid.onespan.cloud/v1/users?locked=false&offset=20&limit=20

In the example, the Offset parameter has been set to 20. The Limit parameter has been set to 20, and the boolean Locked attribute has been set to False. This would return 20 unlocked users, starting at the 20th user in your list.

Executing the Request

At this point, we are ready to make the REST call to Users Query endpoint 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” GET HTTP 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 of a successful “/users” API call.

 

 {

   "total": 20,

   "offset": 0,

   "limit": 20,

   "count": 19,

   "users": [

      {

        "created": "2020-05-08T22:04:35Z",

        "domain": "ospanuser-mail",

        "enabled": true,

        "isPasswordSet": true,

        "lastModified": "2020-05-08T22:22:09Z",

        "lastPasswordUpdate": "2020-05-08T22:04:35Z",

        "locked": false,

        "userID": "iaaUser1",

        "vdpDeliveryMethod": "Default",

        "emailAddress": "[email protected]",

        "mobilePhoneNumber": "+1 (555) 555 5555"

      },

      {

        "created": "2020-05-27T10:35:52Z",

        "domain": "ospanuser-mail",

        "enabled": true,

        "isPasswordSet": true,

        "lastModified": "2020-05-27T10:35:53Z",

        "lastPasswordUpdate": "2020-05-27T10:35:52Z",

        "locked": false,

        "userID": "any.anyl",

        "vdpDeliveryMethod": "Default",

          "authenticators": [

            "VDS0119940",

            "VDS0119940-2",

            "VDS0119940-1"

          ],

    "emailAddress": "[email protected]",

    "mobilePhoneNumber": "+12015554584"

      },

      .....

 }

The following table gives more detailed information on each of the properties from the Response payload above.

Each entry in the users’ array in the table above will contain at least the following fields.

In this blog, we demonstrated how to utilize the User Query endpoint and modify its parameters to pull out the current list of registered users in your sandbox account. Stay tuned for more blog posts about using the IAA Sandbox API. In the meantime, if you have any questions, feel free to reach us on the OneSpan Community Portal Forums. 

Check out more of the Users’ category endpoints:

• User Register Endpoint
• User Unregister Endpoint
• User Update Endpoint/a>

OneSpan Developer Community

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

Join Today