Ping SDKs

Reset registered devices over REST

As described in Recover 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 registering a new device.

Additional support is required for users who lose mobile devices but did not 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.

Reset OATH devices

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

When making a REST API call, specify the realm in the path component of the endpoint.

Authenticate the request with the SSO cookie token belonging to an administrator.

  • Advanced Identity Cloud

  • Self-managed PingAM server

The following example resets the OATH devices for a user in the alpha realm.

In PingOne Advanced Identity Cloud, use the _ID property of the user, not their username. The demo users' _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

Reset OATH device
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "<session-cookie-name>: AQIC5w…​2NzEz*" \
--data '{}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/oath?_action=reset'

The following example resets the OATH device of a user named demo in a realm called mySubrealm:

Reset OATH device
$ 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/demo/devices/2fa/oath?_action=reset'
Result
{
    "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, perform an HTTP POST to /users/{user}/devices/2fa/push?_action=reset.

When making a REST API call, specify the realm in the path component of the endpoint.

Authenticate the request with the SSO cookie token belonging an administrator.

  • Advanced Identity Cloud

  • Self-managed PingAM server

The following example resets the push devices for a user in the alpha realm.

In PingOne Advanced Identity Cloud, use the _ID property of the user, not their username. The demo users' _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

Reset push device
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "<session-cookie-name>: AQIC5w…​2NzEz*" \
--data '{}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/push?_action=reset'

The following example resets the push device of a user named demo in a realm called mySubrealm:

Reset push device
$ 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/demo/devices/2fa/push?_action=reset'
Result
{
    "result":true
}