--- title: Reset registered devices using REST description: As described in Recover after replacing a lost device, a user who has lost a mobile phone registered with Advanced Identity Cloud can register a replacement device by authenticating using a recovery code, deleting their existing device, and then registering a new device. component: pingoneaic page_id: pingoneaic:am-authentication:authn-mfa-reset-devices canonical_url: https://docs.pingidentity.com/pingoneaic/am-authentication/authn-mfa-reset-devices.html keywords: ["Authentication", "Multi-factor Authentication (MFA)"] page_aliases: ["authentication-guide:authn-mfa-reset-devices.adoc"] section_ids: authn-mfa-reset-oath-devices: Reset OATH devices authn-mfa-reset-push-devices: Reset push devices authn-mfa-delete-webauthn-devices: Delete WebAuthn devices authn-mfa-reset-bound-devices: Delete bound devices refresh-push-device-ids: Refresh push device IDs --- # Reset registered devices using 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 Advanced Identity Cloud 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. Advanced Identity Cloud 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. Prefix each realm in the hierarchy with the `realms/` keyword. For example, `/realms/root/realms/alpha`. The following examples assume that you have [obtained an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html) with the appropriate scopes. | | | | - | -------------------------------------------------------------------------------------------------------- | | | The API calls reference the user by `_id`. You can get this ID from the raw JSON for the user's profile. | ## 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 for a user in the `alpha` realm. The user's `_id` in this example is `014c54bd-6078-4639-8316-8ce0e7746fa4`. ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --header "authorization: Bearer access-token" \ --data '{}' \ 'https:///am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/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 the push devices for a user in the `alpha` realm. The user's `_id` in this example is `014c54bd-6078-4639-8316-8ce0e7746fa4`. ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --header "authorization: Bearer access-token" \ --data '{}' \ 'https:///am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/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 in the `alpha` realm. The user's `_id` in this example is `014c54bd-6078-4639-8316-8ce0e7746fa4`. ```bash $ curl \ --request GET \ --header "authorization: Bearer access-token" \ 'https:///am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/webauthn?_queryFilter=true' { "result": [ { "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "_rev": "163664231", "createdDate": 1749572704744, "lastAccessDate": 1749658650801, "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 "authorization: Bearer access-token" \ 'https:///am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/webauthn/ff1db8bf-d2d7-46e1-926a-568b877f87a5' { "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "_rev": "1642022518", "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "recoveryCodes": [ ... ], "createdDate": 1749572704744, "lastAccessDate": 1749658650801, "credentialId": "XGJpYNYv4AHG9sHHgxFfTw", "algorithm": "SHA256withECDSA", "deviceName": "New Security Key", "signCount": 0, "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 retrieves a list of bound devices for a user in the `alpha` realm. The user's `_id` in this example is `014c54bd-6078-4639-8316-8ce0e7746fa4`. ```bash $ curl \ --request GET \ --header "authorization: Bearer access-token" \ 'https:///am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/binding?_queryFilter=true' { "result": [ { "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "_rev": "163664231", "createdDate": 1749572704744, "lastAccessDate": 1749658650801, "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 "authorization: Bearer access-token" \ 'https:///am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/binding/ff1db8bf-d2d7-46e1-926a-568b877f87a5' { "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "_rev": "1642022518", "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "recoveryCodes": [ ... ], "createdDate": 1749572704744, "lastAccessDate": 1749658650801, "deviceId": "e2e84b5d2a927abdcb85570bac9701c390a92751", "deviceName": "iOS Device", "signCount": 0, "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, 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). | ## Refresh push device IDs The [Push Notification service](push-authentication-journeys.html#auth-mfa-push-notification-service) relies on device tokens or IDs issued by the Android and iOS platforms to deliver notifications to end users. These platforms occasionally issue new device tokens. Depending on the platform, there are several reasons a device ID might change: * Android * iOS * JavaScript On Android, the instance ID is deleted or changes if any of the following occurs: * An app is restored on a new device. * The end user uninstalls and reinstalls the app. * The end user clears app data. On iOS, the device ID is stored in the Keychain. This means the ID persists when the app is removed. However, the device ID is deleted or changes if any of the following occurs: * The end user wipes or factory resets the phone. * The end user migrates to a new phone. * The keychain is programmatically deleted from the phone. * The device ID is programmatically deleted from the Keychain. * The keychain identifier in the `forgerock_keychain_access_group` configuration property changes. In JavaScript, the device ID is deleted or changes if any of the following occurs: * The browser window creates the device ID while in private or incognito mode. Closing the browser removes the ID. * The browser removes the ID when cleaning up old data to accommodate new data. * The browser is uninstalled and reinstalled. The ID is removed. * The end user removes the device ID by clearing the browser data. To make sure push notifications are received correctly, the Push Notification service must have the most recent device ID for a particular device. When a new device ID is issued on a device, the following steps must occur: 1. The Ping SDKs send an HTTP POST request to the `push/sns/message` endpoint with the `refresh` action. For example: ```bash https:///am/json/realms/realm-name/push/sns/message?_action=refresh ``` The request includes the `mechanismUid`, `username`, and a JWT that includes the new `deviceID`. 2. The Push Notification service decodes the JWT and extracts the new `deviceID`. 3. The Push Notification service locates the user's push device profile, based on the `username`, and updates the value of the `deviceID`. | | | | - | ------------------------------------------------------------------------------------------------------- | | | If you're not using the Ping SDKs, you must adapt your authenticator application to follow these steps. |