OneSpan Developer: Intelligent Adaptive Authentication — Users Query Endpoint

Hakim Aldaoub, August 5, 2020
OneSpan Developer: Intelligent Adaptive Authentication — Users Query Endpoint
th, td { padding: 20px !important; text-align: center !important; } -->

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 your users. 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 User Query API, you must first be a OneSpan Community member and sign up for a free Intelligent Adaptive Authentication sandbox account. Check out our previous blog, OneSpan Cloud Solutions In Action - MyBank Web Portal Demo, Part 1 for 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 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:  

Augs5th20_1_0

 
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.

Parameter Description   Field Data Type
userID User ID of the user to search for Type: string
Example: “iaa_user1” or “*” to list all the accounts up to 100 accounts, it supports Wildcards.
domain   Domain wherein to search for user accounts.   Type: string
Example: ospanuser-mail
locked User account lock status Type: boolean
Example: “True” or “False”
offset

Index of the first user account returned. The offset parameter is most important when there are over 100 users registered, it will be used to paginate through the registered accounts starting from the specified value

Type: integer
Default value : 0
Example: 100 (this will list the users from the 100th account, and the number of the accounts listed will depend on the “limit” parameter)


limit
Number of user accounts returned. It plays an important role with the “offset” parameter to customize the returned list when the accounts number past 100 accounts Type: integer
Default value : 20
Max Value :100
Example: 20

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.

July8th20_2_0

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.

JSON Response Object     Description Data Type
count*    Number of user accounts returned.    Type: integer
Example: 19
limit*
  
Maximum number of user accounts requested.     Type: integer
Example: 20
offset* Index of the first user account returned. Type: integer
Example: 0 to start from the first index
total*
       
Total number of user accounts that match the 
query input parameters.
Type: integer
Example: 3
users*
       
A list of the user accounts returned, each object in the list is described in the table below.

Type: A JSON array of the selected user accounts.
Example: see the response above

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

Field in Users’ Array Description Data Type
created*    Creation timestamp for the user account.  Type: string
Example: 2019-02-04T11:42:39Z
domain*
    
Domain in which the user account resides. Type: string
Example: ospanuser-mail
enabled* 
    
Specifies whether the user account is enabled or not. Type: boolean
Example: “True” or “False”
isPasswordSet*  Specifies whether the user account has a static password set or not.    Type: boolean
Example: “True” or “False”
lastModified* 
    
Last modified timestamp for the user account.

Type: string
Example: 2019-02-04T11:42:39Z


lastPasswordUpdate*   
Static password last update timestamp. Type: string
Example: 2019-02-04T11:42:39Z
locked* Specifies whether the user account is created in a locked state or not.     Type: boolean
Example: “True” or “False”
mdcProfile* Message Delivery Component (MDC) profile for sending Virtual OTP. Type: string
example: EUROPE
userID* Identifier for the user. Type: string
example: iaa_user1
vdpDeliveryMethod*     Delivery method for sending Virtual OTP.  

Type: string
Example: SMS

authenticators  A list of the authenticators assigned to each user. Type: JSON Array
example: ["VDS0119940",...]

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. 

OneSpan Developer Community

OneSpan Developer Community

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

Join Today