# Account recovery

Page contents

Overview
Backup Based Recovery
- Requirements
- Supported backup types
Token authorisation
How to implement account recovery
Detecting recovery on a device

# Overview

Our account recovery feature allows the end-user to recover their registration without the need for reactivation with a new activation code.

Account recovery is currently only supported with the EncapRecoveryMethodBackup recovery method. For further information, see Backup Based Recovery below.

# Backup Based Recovery

Backup based recovery uses a recoveryCode. This is a secret code that is either provided or generated by the end-user, and is only known by them.

The parameter for backup based recovery is EncapBackupRecoveryParameter.

# Requirements

The end-user is required to have:

An Apple ID.
iCloud Keychain enabled on their mobile device (only required for iCloud backups).

# Supported backup types

iCloud backup.
Encrypted and unencrypted computer-based backup on Mac or PC.

Want to learn more?

See Apple's support documentation on Backup methods for iPhone, iPad and iPod touch (opens new window) for additional details.

# Token authorisation

Operations introduced in the account recovery feature require an EncapToken. This token is used to authorise the next operation after a successful activation or authentication.

For example, this makes it possible to implement an activation flow that both activates the user and sets up recovery for the registration, without an additional authentication.

The authorisation token is issued by our server and returned back to the app as a response when performing certain SDK operations.

To get an authorisation token, you have to specify what purpose (EncapTokenPurpose) you are going to use the token for in the finish operation in the SDK. You can find an overview of the operations that can yield a token below.

Note

Operations will not yield a token unless an EncapTokenPurpose is provided.

# Operations that can yield a token

finishActivation
finishAuthentication
finishAddOrUpdateOfRecovery
finishRecovery
finishDeleteRecovery

# Operations that require a token

startAddOrUpdateOfRecoveryMethod
startDeleteRecovery

# Token Purpose

EncapTokenPurposeAddOrUpdateRecovery
EncapTokenPurposeDeleteRecovery
EncapTokenPurposeNone

Note

The default value is EncapTokenPurposeNone.

# How to implement account recovery

The operations addOrUpdateRecovery and deleteRecovery require an EncapToken. See the operations that can yield a token section for a complete list.

# How to get a token

You can request an EncapToken by setting the tokenPurpose on the EncapAuthParameter.
- If adding or updating recovery, you should use EncapTokenPurpose.addOrUpdateRecovery.
- If deleting recovery, you should use EncapTokenPurpose.deleteRecovery.

Example: How to request a token during activation

EncapController.shared().startActivation(withCode: nil) { startActivationResult in                

    let authParameter = EncapDevicePinAuthParameter(pinCode: "1234")
    authParameter.tokenPurpose = .addOrUpdateRecovery
    
} onError: { error in
    // Error
}

The token will be returned with the usual operation response. You can access it using the example shown below.

Example: How to access a token

EncapController.shared().finishActivation(with: EncapActivationParameters(authParameter: authParameter)) { finishActivationResult in
    // Token will be available by accessing finishActivationResult.encapToken        
} onError: { error in
    // Error
}

# Activate account recovery

Next, you have to add account recovery and connect it to the end-user's registration. You can do this by performing addOrUpdateRecovery. This operation requires a valid EncapToken and EncapRecoveryParameter for the type of recovery method that should be activated.

Example: How to activate account recovery

EncapController.shared().startAddOrUpdateOfRecoveryMethod(with: encapToken) { startAddOrUpdateRecoveryResult in
    let recoveryParameter = EncapBackupRecoveryParameter(recoveryCode: "123456")
    
    EncapController.shared().finishAddOrUpdateOfRecoveryMethod(with: recoveryParameter) { finishAddOrUpdateRecoveryResult in
        // Success
    } onError: { error in
        // Error
    }
    
} onError: { error in
    // Error
}

# Perform account recovery

You can recover an end-user's registration by using the startRecovery and finishRecovery operations. This works similarly in concept to the activation process, where a new authentication method must be selected and enabled.

You can only enable one authentication method for a single recovery. If you want to add more authentication methods, then these can be enabled by using the addOrUpdate operation.

Example: How to perform an account recovery

EncapController.shared().startRecovery { encapStartRecoveryResult in
    
    let recoveryParameter = EncapBackupRecoveryParameter(recoveryCode: "123456")
    let faceIDAuthParameter = EncapDeviceFaceIDAuthParameter()
    
    EncapController.shared().finishRecovery(with: recoveryParameter, authParameter: faceIDAuthParameter) { encapFinishRecoveryResult in
        // Success
    } onError: { error in
        // Error
    }
    
} onError: { error in
    // Error
}

What is the recovery code?

The recoveryCode is a secret code that is provided by the end-user, and is only known by them.

The end-user chooses the recovery code, which is a parameter to the finishAddOrUpdateRecovery() operation.
The end-user must then provide the same recovery code as a parameter to the finishRecovery() operation.
The end-user's choice of authentication method to activate is also a parameter to the finishRecovery() operation.

# Delete a recovery

You can remove an active recovery by performing the deleteRecovery operation.

Example: How to delete a recovery

EncapController.shared().startDeleteRecovery(with: EncapToken) { startDeleteRecoveryResult in
    EncapController.shared().finishDeleteRecovery(with: EncapBackupRecoveryParameter(recoveryCode: "")) { finishDeleteRecoveryResult in
        // Success
    } onError: { error in
        // Error
    }

} onError: { error in
    // Error
}

# Detecting recovery on a device

You can check whether account recovery has been activated on a device by using the method:

isRecoveryActivatedWithError

You can use the following app flow to detect that a restore from backup has occurred:

Check that isActivatedLocallyWithError is returning false.
Check that isRecoveryActivatedWithError is returning true before performing an account recovery.

Identify the activated recovery method

You can use activatedRecoveryMethods to identify the activated recovery method.

← Authentication methods App attestation →