OneSpan Developer: Intelligent Adaptive Authentication – Check Activation Status
For the past few weeks, we have demonstrated how to leverage various endpoints of OneSpan Intelligent Adaptive Authentication (IAA) through the Interactive Sandbox API. In this week’s blog, we will continue the ongoing series and explain how to check the activation status of a new user upon registration. For this purpose, we will use the “/registrations/check-status” endpoint in the Open API Swagger editor.
Before We Begin:
Prior to exploring the “/registrations/check-status” 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.
Introduction
The “/registrations/check-status” endpoint allows you to check the current activation status of a new user’s trusted device. This will give you an idea whether the Orchestration SDK integrated with your application has completed its activation on the trusted device, or whether further actions are required to complete the activation process. As we move ahead in this tutorial, you will notice how the “check-status” endpoint is fairly easy to leverage and therefore easy to integrate with your solution.
Navigate to Check-Status Endpoint:
In order to experiment with the “check-status” endpoint, navigate to the IAA Sandbox Interactive API of your OneSpan Community account. In the Open API Swagger editor, expand the “Provisioning” resource. You will then find an entry for “check-status” HTTP Post method as shown in the image below.
Check-status Endpoint URL
The request URL for this API call will resemble the URL below:
https:// {your_tenant_ID}.sdb.tid.onespan.cloud/v1/registrations/check-status
You won’t need to provide this URL during the tutorial. It is only to show the structure of the URL. The URL will automatically be assigned in the Interactive API when calling the web service.
Check Activation Status in Action
Register a User
For the purpose of the example, we will need to register a new user account, then check the status of its activation. For a complete explanation on how to register a user, check “OneSpan Developer: Intelligent Adaptive Authentication - User Registration” blog.
Following a successful registration, you will get a 200-OK Response Status Code indicating the successful registration of the user. From there, we will proceed with the example and check the activation status of the user on the trusted device.
Check-Status Request Body
The request body of the check-status endpoint call contains three JSON objects. Only the “Login” field is mandatory, while the other two are optional. See the table below for the field descriptions:
| JSON Data Fields | Description | Field Data Type |
|---|---|---|
| login* | Identifier for the user for whom to perform an activation check. | Type: string minLength: 1 maxLength: 255 Example: iaa_user |
| domain | Domain in which the user account resides. | Type: string minLength: 1 maxLength: 255 Example: ospanuser-mail |
| timeoutSeconds | The time after which the request is timed-out for the synchronous call of the endpoint, if this field not provided the endpoint will automatically be called in an asynchronous way. | Type: integer example: 10 |
The JSON formatted request body of the “registrations/check-status” endpoint will look like the example below
{
"login": "userid1",
"Domain": "ospanuser-mail",
"timeoutSeconds": 10
}
Synchronous vs Asynchronous
Checking the activation status could either happen ssynchronously or asynchronously. If synchronous, the field "timeoutSeconds" is required. When provided, the call to the check-status endpoint will automatically be synchronous. That means checking the activation status will continue while within the time duration that is provided in seconds. In an asynchronous method, the endpoint will check the status of the activation instantly upon the call. To make an asynchronous call, the "timeoutSeconds" field must be omitted from the request payload of “check-status” endpoint. This is what differentiates the invocation for the two mechanisms.
Calling the Check-Status Endpoint:
Now it is the time to check the activation status of the new user for OneSpan IAA. To make the API call, click on the “Try it out” button shown in the screenshot below, on the right side of the “registrations/check-status” Post 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.
Activation Status API Call Response Body:
Below is an example of a returned response body of the “registrations/check-status” API call.
{
"activationStatus": "pending"
}
Activation Status Types
The only returned field in the response payload is "activationStatus". It is of type String and its value will be one of the device activation statuses below:
| Activation Status Type | Meaning |
|---|---|
| unknown | No pending activation found for the user indicated in the request payload “login” field. |
| pending | The activation process is in progress for the user account indicated in the request payload “login” field. |
| activated | The activation process has been completed on the trusted device of the user account indicated in the request payload “login” field. |
| timeout | The activation process has been timed-out before the activation had been completed. |
Upon the registration, the activation status will display as “Pending” until the user finishes activation. If the activation did not occur within 10 minutes, the session will expire and the activation status will turn into an “Unknown”.
In this blog, we demonstrated how to check the activation status of an end user account using the check-status endpoint of the IAA Sandbox Interactive API. By now you should have the knowledge to use it and integrate it to your solution. If you have any questions, feel free to reach us on the OneSpan Community Portal Forums.
OneSpan Developer Community
Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.
Join Today
