Resetting Registered Devices by using REST

As described in "Recovering After Replacing a Lost Device", a user who has lost a mobile phone registered with AM can register a replacement device by authenticating using a recovery code, deleting their existing device, and then re-registering a new device.

Additional support is required for users who lose mobile phones but did not save their recovery codes when they initially registered the phone, and for users who have used up all their recovery codes.

AM provides a REST API to reset a device profile by deleting information about a user's registered device. Either the user or an administrator can call the REST API to reset a device profile. Device profile reset can be implemented as follows:

Administrators provide authenticated users with a self-service page that calls the REST API to let the users reset their own device profiles.
Administrators can call the REST API themselves to reset users' device profiles.
Administrators can call the REST API themselves to reset a device when the HOTP counter exceeds the HOTP threshold window and requires a reset.
Note
The reset action deletes the OATH device profile, which by default has a limit of one profile per device, and sets the Select to Enable Skip option to its default value of Not Set.

Reset OATH Devices

To reset a user's OATH device profile, perform an HTTP POST to the /users/user/devices/2fa/oath?_action=reset endpoint.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example /realms/root/realms/customers/realms/europe.

The following example resets the OATH devices of a user named myUser in a subrealm of the Top Level Realm called mySubrealm:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
--data '{}' \
https://openam.example.com:8443/openam/json/realms/root/realms/mySubrealm/users/myUser/devices/2fa/oath?_action=reset
   {
    "result":true
}

Reset Push Devices

To reset push devices over REST, perform an HTTP POST to the /users/user/devices/2fa/push?_action=reset endpoint as follows:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
--data '{}' \
https://openam.example.com:8443/openam/json/realms/root/realms/mySubrealm/users/myUSER/devices/2fa/push?_action=reset"
   {
    "result":true
}

Resetting Registered Devices by using REST

Note