--- title: Reset registered devices over REST description: Use PingAM REST APIs to reset or delete user-registered multi-factor authentication devices including OATH, push, WebAuthn, and bound devices component: pingam version: 7.5 page_id: pingam:am-authentication:authn-mfa-reset-devices canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/authn-mfa-reset-devices.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Authentication", "Multi-factor Authentication (MFA)"] page_aliases: ["authentication-guide:authn-mfa-reset-devices.adoc"] superseded_by: https://docs.pingidentity.com/pingam/8.1/am-authentication/authn-mfa-reset-devices.html section_ids: reset_oath_devices: Reset OATH devices reset_push_devices: Reset push devices delete_webauthn_devices: Delete WebAuthn devices delete_bound_devices: Delete bound devices --- # Reset registered devices over REST As described in [Recover after replacing a lost device](authn-mfa-using-lost.html), 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 registering a new device. Additional support is required for users who lose mobile devices but didn't save their recovery codes when they initially registered the device, 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. Both the user and administrator accounts can use the REST API to reset a device profile. Administrators can: * Provide authenticated users with a self-service page that calls the REST API to reset their devices. * Call the REST API themselves to reset a user's device profiles. * Call the REST API themselves to reset a device that is out of sync, where the HOTP counter exceeds the HOTP threshold window and requires a reset. 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`. ## Reset OATH devices To reset a user's OATH device profile, send an HTTP POST request to the `/users/user/devices/2fa/oath?_action=reset` endpoint. The following example resets the OATH devices of a user named `bjensen` in a realm called `alpha`: ```bash $ 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/alpha/users/bjensen/devices/2fa/oath?_action=reset' { "result":true } ``` 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 push devices To reset push devices over REST, send an HTTP POST request to the `/users/user/devices/2fa/push?_action=reset` endpoint. The following example resets push devices for a user named `bjensen` in a realm called `alpha`: ```bash $ 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/alpha/users/bjensen/devices/2fa/push?_action=reset' { "result":true } ``` ## Delete WebAuthn devices The `reset` action isn't implemented on the `webauthn` endpoint. You can delete a WebAuthn device over REST as follows: 1. Retrieve a list of WebAuthn devices associated with a user by querying the `users/user/devices/2fa/webauthn` endpoint. The following example retrieves a list of WebAuthn devices for a user named `bjensen` in a realm called `alpha`: ```bash $ curl \ --request GET \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ 'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/bjensen/devices/2fa/webauthn?_queryFilter=true' { "result": [ { "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "_rev": "163664231", "credentialId": "XGJpYNYv4AHG9sHHgxFfTw", "deviceName": "New Security Key", "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "deviceManagementStatus": false } ], "resultCount": 1, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 } ``` 2. Delete the required WebAuthn device from the user by sending an HTTP DELETE request to the `users/user/devices/2fa/webauthn/device-id` endpoint, including the ID of the WebAuthn device you want to delete: ```bash $ curl \ --request DELETE \ --header "Accept-API-Version: resource=1.0" \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ 'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/bjensen/devices/2fa/webauthn/ff1db8bf-d2d7-46e1-926a-568b877f87a5' { "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "_rev": "1642022518", "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "recoveryCodes": [ ... ], "credentialId": "XGJpYNYv4AHG9sHHgxFfTw", "algorithm": "SHA256withECDSA", "deviceName": "New Security Key", "key": { ... } } ``` 3. Repeat step 2 to delete additional WebAuthn devices for the user, if needed. ## Delete bound devices The `reset` action isn't implemented on the `binding` endpoint. You can delete a bound device over REST as follows: 1. Retrieve a list of bound devices for a user by querying the `users/user/devices/2fa/binding` endpoint. The following example lists the bound devices for a user named `bjensen` in a realm called `alpha`: ```bash $ curl \ --request GET \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ 'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/bjensen/devices/2fa/binding?_queryFilter=true' { "result": [ { "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "_rev": "192142989", "deviceId": "e2e84b5d2a927abdcb85570bac9701c390a92751", "deviceName": "iOS Device", "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "deviceManagementStatus": false } ], "resultCount": 1, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 } ``` 2. Delete the required bound device from the user by sending an HTTP DELETE request to the `users/user/devices/2fa/binding/device-id` endpoint, including the ID of the bound device you want to delete: ```bash $ curl \ --request DELETE \ --header "Accept-API-Version: resource=1.0" \ --header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \ 'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users/bjensen/devices/2fa/binding/ff1db8bf-d2d7-46e1-926a-568b877f87a5' { "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "_rev": "1642022518", "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "recoveryCodes": [ ... ], "deviceId": "e2e84b5d2a927abdcb85570bac9701c390a92751", "deviceName": "iOS Device", "key": { ... } } ``` 3. Repeat step 2 to delete additional bound devices for the user, if needed. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Deleting a bound device on the server doesn't remove the private keys from the device.Instead, you can use the Ping SDKs to remove the bound device from the server, and then remove the keys from the device. Learn more in [Unbind devices by deleting keys](https://docs.pingidentity.com/sdks/latest/sdks/use-cases/how-to-bind-devices.html#unbind). |