OneSpan Developer: User Update Patch Method

Hakim Aldaoub, February 16, 2021

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/{[email protected]}

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:

OneSpan-BlogImage[UserUpdatePatchMethod]1.png

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 [email protected], 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.

OneSpan-BlogImage[UserUpdatePatchMethod]2

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
maxLength: 64
Example: “[email protected]

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
Example: "2021-02-11T02:02:54Z”

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:

 

OneSpan Developer: Intelligent Adaptive Authentication – Authenticator Assignment Endpoint

OneSpan Developer Community

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

Join Today