OneSpan Developer: User Update Patch Method
In any institution, user profiles could require alterations for one or more reasons. This could be for the user’s mailing address, phone number, or simply the user preferences. The update feature is one of the CRUD operations, and it is essential to user-centric applications. OneSpan Intelligent Adaptive Authentication (IAA) provides the user’s update endpoint to alter the user account properties through the Sandbox Interactive API. Today, we will explain how to update one or more fields in a user profile using a single RESTful call.
Before We Begin
Prior to exploring how to update a user profile, 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/users/{userID@domain}
You won’t need to provide this URL during the tutorial. We have included here merely as an example of the URL structure. Your actual request URL will be automatically assigned in the Interactive API when calling the web service.
Try It Out
In order to experiment with the Events Validation API, navigate to the IAA Sandbox Interactive API document in your OneSpan Community account. In the Open API Swagger editor, expand the “Users” resource. You will then find an entry for the Users update HTTP Patch method as shown in the image below:
URL Path Parameters:
For the purpose of this user’s update patch call, there is a required path parameter for the unique user identifier. The path parameter is formatted as userID@domain, which includes the userID that has been activated on the trusted device as well as the user domain following the “@” sign. Replace the user domain with the “Sandbox User” string shown below. You can find this string in your Sandbox details section under the “Intelligent Adaptive Authentication” tab of your Sandbox homepage.
Users Update Request Body
The request body will look like the example below. Note that it could be only one of the lines below to update the specified field for the user account specified by ID in the path parameter.
{
"emailAddress": "[email protected]",
"enabled": true,
"mdcProfile": "EUROPE",
"mobilePhoneNumber": "+1 (508) 366 3437",
"phoneNumber": "+1 (508) 366 3437",
"staticPassword": "TestABCD",
"vdpDeliveryMethod": "Email"
}
Request Payload
Note: There are no mandatory fields in the JSON payload, since the endpoint purpose is to update one or more fields as required by the calling application.
Below is a list of the fields that could be updated using the endpoint:
JSON Required Data Fields | Description | Field Data Type |
---|---|---|
emailAddress | The email address to be updated for the end-user. |
Type: string |
enabled | This field is to determine if the end-user’s account will be enable or disabled. assigning True will enable the account and false will disable it. | Type: boolean Example: True |
mdcProfile | The specific Message Delivery Component profile for virtual Digipass messages for a specific user. This takes precedence over the MDC profile specified in the user policy. | Type: string maxLength: 100 example: EUROPE |
mobilePhoneNumber | The mobile phone number of the end-user. | Type: string Pattern: ^[\+\-\(\)0-9 ]{0,20}$ maxLength: 64 Example: "+1 (508) 366 3437” |
phoneNumber | The phone number of the end-user. | Type: string Pattern: ^[\+\-\(\)0-9 ]{0,20}$ maxLength: 64 Example: "+1 (508) 366 3437” |
staticPassword | The static password of the user. | Type: String MinLength: 8 MaxLength: 255 Example: TestABCD |
vdpDeliveryMethod | The delivery method for sending the Virtual Digipass. This could be through email, SMS, or voice. |
Type: String Example: Email |
Calling the Endpoint
Now we are ready to make a RESTful call to update the user profile 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 PATCH 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 with a 200 response code which indicates a successful request.
{
"created": "2021-02-11T02:02:54Z",
"domain": "osiaa4-mailinator",
"enabled": true,
"isPasswordSet": true,
"lastModified": "2021-02-11T03:17:16Z",
"lastPasswordUpdate": "2021-02-11T02:02:54Z",
"locked": false,
"mdcProfile": "EUROPE",
"userID": "iaaend1",
"vdpDeliveryMethod": "SMS",
"authenticators": [
"VDS0058266",
"VDS0058266-2",
"VDS0058266-1"
],
"emailAddress": "[email protected]",
"mobilePhoneNumber": "+1 (508) 366 3437",
"phoneNumber": "+1 (508) 366 3437"
}
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 |
---|---|---|
created * | The creation timestamp for the user account. |
Type: String |
domain * | The domain in which the user account to be updated resides. | Type: string minLength: 1 maxLength: 255 example: ospanuser-mail |
enabled * | The field that specifies whether the user account is enabled or not. | Type: Boolean example: true |
isPasswordSet * | The field that specifies whether the user account has a static password set or not. | Type: Boolean example: true |
lastModified* | The timestamp for the last time the authenticator has been modified. | Type: string Example: 2019-02-04T11:42:39Z |
lastPasswordUpdate* | The timestamp for the last time the static password has been updated by the admin or the end-user. | Type: string Example: 2019-02-04T11:42:39Z |
Locked* | The field specifies whether the user account is created in a locked state or not. |
Type: Boolean example: true |
mdcProfile* | The Message Delivery Component (MDC) profile for sending Virtual OTP. |
Type: string example: Europe |
UserID* | The user ID to which the authenticator is assigned. |
Type: string Example: “iaa_user1” |
vdpDeliveryMethod* | The preferred delivery method for sending Virtual OTP. |
Type: string Example: “SMS” |
HTTP Response Status Codes:
The table below shows the expected response codes when attempting to delete a user account:
Response Status Code | Meaning |
---|---|
200 | The user account is updated. |
400 | Input data errors. |
403 | The command is prohibited for the tenant admin account. |
404 | The user account is not found. |
409 | The user account could not be updated. |
500 | Internal error, sub service failure, server crash. |
Today, we covered how to update one or more properties for an existing user profile. We also covered how to make this request using the OneSpan Interactive API. If you have any question, please reach out on the OneSpan Community Portal Forums.
Check out more of the Users’ category endpoints: