Account recovery

About account recovery

Our account recovery feature enables your end-users to recover their account when they have lost access to it, using your app. This means that your end-users can quickly return to your services, without the need to perform a costly and time-consuming re-onboarding.

PSD2 compliant

This feature has been reviewed by a third party and is approved as a PSD2-compliant recovery method.

When to use account recovery

Our account recovery feature is best fit for use cases when your end-user no longer has access to an active device. There are multiple reasons why an end-user may need to recover their account, such as:

• If their device has been lost, broken or stolen.
• If they have deleted your application (Android only).

If your end-user still has access to their old device, then we recommend that you perform a recovery/activation of the new device by approving the operation on the old device instead.

How does account recovery work?

Prerequisites

To be able to use our account recovery feature:

• You need to configure account recovery in the application configuration.
• Your end-user's device needs to have backup functionality enabled. This is enabled by default.
  Supported backup providers

  The supported backup providers are Google Cloud and Apple iCloud.

• Optional: If using server-side face authentication to protect the recovery backups (as opposed to a recovery code), then you also need to configure this feature in the application configuration.

Basic flow for an account recovery

1. Your end-user adds account recovery in your app.
2. As a result, the recovery credentials are stored in the cloud backup.
3. At a later point in time, your end-user performs an account recovery using your app that has implemented our account recovery feature.

Note

All account recovery-related SDK operations require a valid authorisation token. To find out how to obtain this, see the Token authorisation section.

Token authorisation

When you are using our SDKs for account recovery, you need to provide a token to authorise the operation.

• Authorisation tokens are issued by our server when performing certain SDK operations.
• In these operations, you need to set what purpose you will use the token for.
• The token is returned back to your app as a response.
• This token is used to authorise the next account recovery operation after a successful registration or authentication.

What does this mean?

For example, this makes it possible to implement a flow that both registers the end-user and adds account recovery for the registration, without an additional authentication.

Operations that require a token

An authorisation token is required for the following recovery-related operations:

• addOrUpdateRecovery
• deleteRecovery

Operations that can yield a token

The server will issue an authorisation token for the following operations:

• finishActivation
• finishAuthentication
• finishAddOrUpdateRecovery
• finishRecovery
• finishDeleteRecovery

Note

You will obtain an authorisation token for addOrUpdateRecovery by setting the TokenPurpose to addOrUpdateRecovery in one of the operations specified above.

What does an account recovery look like?

The account recovery can be secured using server-side face authentication or a recovery code.

We recommend server-side face authentication as:

• It is more user-friendly, with no recovery code to remember.
• It enhances security by not having a recovery code which could be shared.

What could it look like for your end-users?

To see what account recovery with face authentication could look like for your end-users, see our Figma prototype.

You can either click the app's interface, or use the arrows below the phone.

Add account recovery using face authentication

Account recovery using face authentication can be added to a registration that has activated face authentication as an authentication method.

The most common approach is to add account recovery in the same flow as when the end-user activates face authentication, however, it is possible to add account recovery at a later stage as well.

Important

If the device deletes server-side face authentication as an authentication method, then the device will no longer be able to recover using face authentication.

Flow 1: Add recovery during activation of face authentication

To add account recovery in the same flow as activating face authentication:

1. Your app performs startAddOrUpdate and finishAddOrUpdate SDK operations to add server-side face authentication as a new authentication method. Simultaneously, your app obtains a valid authorisation token.
2. Your app performs an add recovery flow using startAddOrUpdateRecovery and finishAddOrUpdateRecovery SDK operations.
3. As a result, the recovery credentials are stored in the cloud backup, and the existing face authentication is linked to the recovery.

Sequence diagram

Sequence diagram showing add recovery during activation of face authentication

Flow 2: Add recovery at a later stage

To add account recovery at a later stage, when server-side face authentication has already been added as an authentication method for the the device:

1. Your app obtains a valid authorisation token using startAuthentication and finishAuthentication SDK operations. This is used for the following account recovery operation.
2. Your app performs an add recovery flow using startAddOrUpdateRecovery and finishAddOrUpdateRecovery SDK operations.
3. As a result, the recovery credentials are stored in the cloud backup, and the existing face authentication is linked to the recovery.

Sequence diagram

Sequence diagram showing add recovery at a later stage

Add account recovery using recovery code

Account recovery using a recovery code can be added either during device registration, or at a later stage to an existing registration.

Flow 1: Add recovery during a new registration

To add account recovery during a new registration:

1. Your app obtains a valid authorisation token by performing a standard registration, using startActivation and finishActivation SDK operations. This is used for the following account recovery operation.
2. Your app performs an add recovery flow using startAddOrUpdateRecovery and finishAddOrUpdateRecovery SDK operations.
3. As a result, the recovery credentials are stored in the cloud backup.

Sequence diagram

Sequence diagram showing add account recovery during a new registration

Flow 2: Add recovery at a later stage

To add account recovery at a later stage to an existing registration:

1. Your app obtains a valid authorisation token using startAuthentication and finishAuthentication SDK operations. This is used for the following account recovery operation.
2. Your app performs an add recovery flow using startAddOrUpdateRecovery and finishAddOrUpdateRecovery SDK operations.
3. As a result, the recovery credentials are stored in the cloud backup.

Sequence diagram

Sequence diagram showing add account recovery to an existing registration

Perform an account recovery

To perform an account recovery, your app is restored with startRecovery and finishRecovery SDK operations, using data from the could backup.

• The device ID (deviceId) that you use as a reference remains unchanged when your app is recovered.
• Once a recovery has been performed, it cannot be used again.
• To be able to recover again, your end-users need to add a new recovery on the device.
• For recovery using face authentication, the face authentication method is automatically activated for the recovered device.

Sequence diagram

Sequence diagram showing account recovery being performed

Manage account recovery

Account recovery can be managed with operations to update or delete a recovery.

Update a recovery

To update a recovery:

1. Your app obtains a valid authorisation token using startAuthentication and finishAuthentication SDK operations. This is used for the following account recovery operation.
2. Your app performs an update recovery flow using startAddOrUpdateRecovery and finishAddOrUpdateRecovery SDK operations.

Delete a recovery

To delete a recovery:

1. Your app obtains a valid authorisation token using startAuthentication and finishAuthentication SDK operations. This is used for the following account recovery operation.
2. Your app performs a delete recovery flow using startDeleteRecovery and finishDeleteRecovery SDK operations.

Note

Deleting a recover with face authentication does not delete the face authentication method.

How to implement account recovery

To implement our account recovery feature, you need to:

• Configure the application configuration.
• Configure the mobile SDK.

Configure the application configuration

To use account recovery, you must first configure it in your application configuration. Once it has been configured, all devices using that application configuration have the ability to perform recoveries. To do this:

1. Go to Signicat Dashboard > Products > MobileID > Features > Account recovery.
2. Use the toggle button to enable account recovery, then click Save.

Want to learn more?

To learn more about the configurable properties, see the Account recovery section in our Application configuration feature documentation.

Recovery using face authentication

If using server-side face authentication to protect the recovery backups (as opposed to a recovery code), then you also need to configure server-side face authentication in the application configuration.

To learn how to do this, see the configuration section in our Face authentication feature documentation. If you want to use a recovery code to protect the recovery backups, you can skip this step.

Configure the mobile SDK

You must also configure the SDK for account recovery. To learn how to do this, read the platform-specific documentation using the buttons below:

Configure the Android SDK

Learn how to configure the Android SDK for account recovery

Configure the iOS SDK

Learn how to configure the iOS SDK for account recovery

Events (callback)

Most account recovery operations, including adding and performing an account recovery, are client-initiated operations. We can send events to your server to let it know when these operations occur.

To get events, you need to set up subscriptions in the Signicat Dashboard. To learn how to do this, see our Events documentation.

API integration

We provide endpoints for account recovery that allow you to optionally integrate with the MobileID REST API.

With these endpoints, you can carry out operations such as:

• Determine if a device has set recovery credentials.
• Retrieve information about recovery data and the recoveries performed from devices.
• Disable recovery for a device

Get general recovery information

To get general information about all recoveries performed for an end-user's device, you can use the Get device endpoint in the MobileID Device management API.

The response returns information about an end-user's device, and allows you to verify whether account recovery has been enabled for that specific device.

Note

The recovery information is contained within the device details object. To return this object in the response, you must use query parameter:

detailed=true

Get detailed information about a recovery

To get detailed information about a specific recovery performed for an end-user's device, you can use the Get details of account recovery endpoint in the MobileID Account recovery API.

The response lists risk data and all other attributes created as part of the recovery process, if the operation is finished.

Note

You need the transaction ID (transactionId) of the recovery to use this endpoint.

To learn how to obtain this, see the Useful information section for this API in the MobileID API reference documentation.

Disable recovery for a device

To disable recovery for a specific device, you can use the Update recovery lock endpoint.

If recovery lock is enabled, then the device will be unable to perform any operations related to account recovery.

Note

Locking recovery prevents the device from adding and performing recoveries, even when recovery is enabled in the application configuration.