OneSpan Developer: Intelligent Adaptive Authentication - Authenticators Query Endpoint
![OneSpan-BlogImage-[IAA-Authenticators-Query]](/sites/default/files/styles/blog_detail_image/public/2020-09/OneSpan-BlogImage-%5BIAA-Authenticators-Query%5D_1.jpg?itok=Ht8c0oOU)
Due to their integral role in OneSpan Intelligent Adaptive Authentication (IAA),an entire section was included in the IAA Sandbox Interactive API on the Digipass authenticators. The section comprises each endpoint for handling activities related to authenticators. As an example, with these endpoints you could view, assign, or unassign authenticators to the user accounts and generate activation data. In this blog, we will explore the Authenticators Query endpoint and show how to customize its path parameters. In doing so, we will make an HTTP GET call to list all the authenticators that pertain to a specific account and explain this call through the IAA Sandbox Interactive API.
Before We Begin
Prior to exploring the Authenticator 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.
Endpoint URL
The request URL for this API call will resemble the example below:
https://{your_tenant_ID}.sdb.tid.onespan.cloud/v1/authenticators
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.
Experience It with the Sandbox Interactive API
In order to experiment with the Authenticator Query API, navigate to the IAA Sandbox Interactive API document in your OneSpan Community account. In the Open API Swagger editor, expand the “Authenticators” resource. You will then find an entry for the Authenticators Query HTTP Get method as shown in the image below:
The Authenticators 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 to tailor the call for specific results.
URL Path Parameters:
The Authenticators Query Endpoint encompass various path parameters which help you locate a specific list of the authenticators to customize the query within the Sandbox Platform API. The table below shows the various path parameter options that are used to customize the query:
| Path Parameter | Description | Field Data Type |
|---|---|---|
| serialNumber | Allow to specify whether to list all authenticators, or to find a specific authenticator by providing its Serial number | Type: string Example: VDS0091651 or “*” to list all the accounts up to 100 accounts, it supports Wildcards. |
| domain |
Domain wherein to search for authenticators. | Type: string Example: ospanuser-mail |
| type | Authenticator type. | Type: string example: DAL10 |
| assigned |
Assignment status to filter the results | Type: boolean Example: “True” or “False” |
| offset | Index of the first authenticator returned. The offset parameter is handy when a pagination through the authenticator list is required | Type: integer Default value : 0 Example: 10 (this will list the authenticators from the 10th authenticator, and the number of the authenticator listed will depend on the “limit” parameter) |
| limit | The number of authenticators returned. It plays an important role with the “offset” parameter to customize the returned list of the authenticators | Type: integer Default value : 20 Max Value :100 Example: 4 |
Below is a sample of what the Request URL will look like with some of the parameters added:
https://ospanuser-mail.sdb.tid.onespan.cloud/v1/authenticators?
type=DAL10&assigned=true&limit=20
In the example, the Type parameter has been set to DAL10. The boolean “Assigned” parameter has been set to “True”, and the “Limit” has been set ‘20’. This would return a maximum of 20 already assigned authenticators of type DAL10.
Calling the Endpoint
At this point, we are ready to make a RESTful call to Authenticators Query 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 “/authenticators” 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 “/authenticators” API call.
{
"total": 10,
"offset": 0,
"limit": 20,
"count": 10,
"authenticators": [
{
"applications": [
{
"name": "ACTIVATION",
"type": "MA"
}
],
"created": "2018-09-07T11:31:02Z",
"domain": "osiaa4-mailinator",
"lastModified": "2020-05-28T18:22:07Z",
"serialNumber": "VDS0028610",
"activation": {
"activationsCount": "4",
"lastActivated": "2020-05-28T18:22:06Z",
"locationsCount": "0",
"bound": false
},
"assignedUserID": "userid100000",
"authenticatorType": "DAL10",
"assigned": true
},
…]
Response Payload Fields’ Description
The following table gives more detailed information on each of the properties from the Response payload above.
| Response Object | Description | Data Type |
|---|---|---|
| total* |
It holds the total number of authenticators that match the query input parameters. | Type: integer Example: 3 |
| offset* | Index of the first authenticator returned. | Type: integer Example: 0 to start from the first index |
| limit* | Maximum number of user authenticators requested. | Type: integer Example: 20 |
| count* | Number of authenticators returned. | Type: integer Example: 19 |
| authenticators* | A list of the authenticators returned. Each object in the list is described in the following table. | Type: A JSON array of the selected authenticators. Example: see the response payload above. |
The “authenticators” object is the most important part of the JSON response body. It has the information pertaining to each listed authenticator in the response. In the table below, there is the list of all attributes of the authenticators object.
| Data Fields | Description | Data Type |
|---|---|---|
| applications* | The list of applications supported by the authenticator. This attribute is an array that carries the name and the type of each authenticator | Type: JSON list Example: "applications": [{ "name": ACTIVATION", "type": "MA" } ] |
|
assigned* |
This indicates whether this authenticator is assigned to a user. |
Type: boolean Example: True or False |
|
created* |
The creation timestamp for the authenticator. | Type: string Example: 2019-02-04T11:42:39Z |
|
domain* |
The domain in which the user account resides. | Type: string Example: ospanuser-mail |
|
lastModified* |
The last modified timestamp for the authenticator. | Type: string Example: 2019-02-04T11:42:39Z |
|
serialNumber* |
The serial number of the authenticator. |
Type: string Example: “VDS0091651“ |
|
activation |
The activation object will have three attributes, “bound” to indicate if the authenticator is linked to a specific device, “activationsCount” to show the number of activations. “lastActivated” to show the last activated timestamp for the authenticator. “locationsCount” to show the number of activation locations. | Type: JSON list Example: See the response payload above |
| assignedUserID* | The user this authenticator is assigned to. | Type: string Example: “iaa_user1” |
| authenticatorType* | The type of the authenticator. | Type: string Example: “DAL10” |
In this blog, we illustrated how to utilize the Authenticators Query endpoint and modify its parameters to filter through the authenticators available 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 Authenticators’ category endpoints:
OneSpan Developer Community
Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.
Join Today
