OneSpan Developer: Intelligent Adaptive Authentication – Authenticator Unassign
OneSpan Intelligent Adaptive Authentication Sandbox API gives you the control to manage all aspects related to Digipass authenticators. In the previous blog, we showcased how to assign an authenticator for a specific user using the Sandbox Interactive API. Here, we will explore the “Authenticator Unassign” endpoint and show how easy it is to release an authenticator instance that has already been assigned to a user.
Before We Begin:
Prior to exploring the API to unassign a Digipass authenticator, you must first join the OneSpan Community 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, Part1 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/{serial_Number}/unassign
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 Out
In order to experiment with the Authenticators Unassign 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 Unassign HTTP Post method as shown in the image below:
URL Path Parameters:
The only path parameter required for unassigning a specific authenticator is its serial number. Even though that authenticator is tied to a specific user, we do not need to provide the userID or domain anywhere in the HTTP request.
The serialNumber variable is of type String. It is a unique identifier assembled from three letters and seven digits. For example, a serial number could be VDS0066822.
The best way to find the serial number of the authenticator required as a path parameter is through the Authenticators Query endpoint. When making the query, it will be easier to find a linked authenticator if we set the assigned property to True. This way we will only get a list of the authenticators already assigned to a user. For a full reference of the query endpoint, you could visit OneSpan Developer: Intelligent Adaptive Authentication - Authenticators Query Endpoint
Below is a sample of what the Request URL will look like after adding the authenticator serial number and the domain
https://ospanuser-mail.sdb.tid.onespan.cloud/v1/authenticators/VDS0066822/unassign
In the example above, the authenticator with VDS0066822 serial number will be unassigned from the end user.
Calling the Endpoint
At this point, we are ready to make a RESTful call to Authenticator Unassign 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 HTTP 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.
Authenticator Unassign HTTP Response:
The response code that is expected to be returned following a successful authenticator unassign call is 204 meaning (Authenticator unassigned).
The HTTP response of this call will contain no response payload, it will mainly be an entity tag’s response header provided by the server for the current entity state version. This ETag should be treated as opaque, and it could be used to make conditional follow-up requests.
Below is an example of the returned response header of a successful “Authenticators Unassign” API call.
HTTP Response Status Codes:
The table below shows the potential response codes when attempting to unassign an authenticator with an HTTP Post request.
| Response Status Code | Meaning |
|---|---|
| 204 | Authenticator Unassigned |
| 400 | Input data errors. |
| 403 | The command is prohibited for the tenant admin account. |
| 404 | The authenticator linked to the serial number is not found. |
| 409 | The authenticator linked to the serial number is not assigned. |
| 500 | Internal error, sub service failure, server crash. |
In this blog, we explored how to unassign an authenticator instance that has already been linked to an end user account. Stay tuned for more blogs as I continue walking through the different API endpoints. If you have any questions regarding the content, 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
