OneSpan Developer: Intelligent Adaptive Authentication - Authenticators Query Endpoint

Hakim Aldaoub, September 2, 2020
OneSpan-BlogImage-[IAA-Authenticators-Query]

Due to their integral role in OneSpan Intelligent Adaptive Authentication (IAA), Digipass authenticators, we’ve included an entire section on their use in the IAA Sandbox Interactive API. The Authenticators 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 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/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 webservice. 

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:

Sept2nd-1_0.png

 

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.

Sept2nd-2_0

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

 

OneSpan Developer: Intelligent Adaptive Authentication - Authenticators Query Endpoint

OneSpan Developer Community

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

Join Today