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.
| 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 |
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.
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. |
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 |
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 |
| 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.
Check out more of the Users’ category endpoints:
OneSpan Developer Community
Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.
Join Today
