Supporting replacements

Replacing a credential

You may wish to provide a facility for your end-users to collect a replacement credential for scenarios such as the use of a temporary or permanent replacement device.

You can use the RESTful Web API or one of the Server SDKs to request a replacement credential.

  • Requesting a replacement credential will not consume one of your licenses, and the replacement credential will be set to expire at the same time as the credential it replaces

  • The service authentication certificate is required for secure API calls to the RapID Service.

Security considerations

Confirm the end-user's request for replacement

It is vital that your credential replacement process maintains the security of all your end-users. As such you may wish to include an email verification step and other additional security checks such as identity verification.

Credential replacement for a new device

In order to maintain the security of your service it is important that you always use a new anonymous identifier for the new device when issuing a replacement credential for a device that is no longer in your end-user's possession. This allows your web service to prevent access to your service with the old device by no longer allowing access with the old anonymous identifier.

Note: If you have not followed our recommendation to use separate anonymous identifiers for each device you cannot easily do this. You would need to request replacement credentials for all the devices that belong to the end-user whose credential you are replacing. If you didn't do this, your service would not be able to determine whether a connection to your web server is from the old device or from one of the end-user's current devices.

When replacing credentials due to PIN lock out, there is no absolute need to change the anonymous ID, though you may choose to do so for simplicity.

Sample procedure

The following steps illustrate the type of procedure you will need to develop for your web service in order to support credential replacement for your end-users.

  1. Provide a mechanism for an end-user to type their email address and request a replacement credential. This could be a form on your website.
  2. Using your standard procedure for end-user verification, confirm the user's identity.
    • If this is by email, we recommend that you include an additional mechanism to address the possibility that their email has been compromised. For example, in the RapID customer portal we require a primary contact from the same company to confirm the replacement request.
  3. When you have confirmed the legitimacy of a request for a replacement:
    • Create a new anonymous identifier for the end user and update the user database with this new identifier. This prevents access using the old device.
    • POST to the credentials route in the RESTful Web API to request a replacement credential with a new anonymous identifier. https://request.rapidauth.com/rapid/credentials/{old anonymous Id}/replace passing the new anonymous identifier in the JSON body: {"AnonId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"}.
    • The JSON response to this request includes a RequestId
  4. Send an email to the user, including a link containing the RequestId for the replacement request.
  5. When the end-user clicks the link from their device, this opens your RapID-ready mobile app.
  6. The app calls CollectCredential() in the mobile SDK, passing in the RequestId
  7. If this is an old device (i.e. replacement due to PIN lock out), the SDK deletes the old credential and saves the new one, forcing the end-user to create a new PIN.