Account recovery

Keyless is able to recover an account from what we refer to as temporary state.

The temporary state is obtained:

1. from your backend through Keyless Identity Verification Bridge. More in IDV-Bridge.

2. from your client app using the Keyless Mobile SDK.

What follows refers to option 2: obtain the temporary state from the Keyless Mobile SDK.

What is the temporary state?

The Keyless temporary state contains all the necessary information to restore an account. It can be created during enrollment and authentication.

To create and use the temporary state Keyless requires the user biometric.

The temporay state internals are not important but you can expect a string similar to the following that you should pass as-is to recover the account:

"{\"artifact\":{\"family\":\"davideface_lite\",\"version\":\"1.2.0\",\"target\":\"mobile_sdk\",\"liveness\":\"liveness\"},\"core-client-state\":\"BASE_64_STATE\"}"

Obtain the temporary state

Use the shouldRetrieveTemporaryState parameter of the BiomEnrollConfig or BiomAuthConfig depending if you want to retrieve the temporary state during enrollment or authencation flows.

Android

Dunring the enrollment flow:

val enrollConfig = BiomEnrollConfig(shouldRetrieveTemporaryState = true)

Keyless.enroll(
  configuration = enrollConfig,
  onCompletion = { result ->
    when (result) {
      is Keyless.KeylessResult.Success -> {

      	val temporaryState = result.value.temporaryState
      	// store the temporary state on your backend to recover the account in the future

      }
      is Keyless.KeylessResult.Failure -> Log.d("KeylessSDK ", "error code ${result.error.code}")
    }
  }
)

During the authentication flow:

val authConfig = BiomAuthConfig(shouldRetrieveTemporaryState = true)

Keyless.authenticate(
  configuration = authConfig,
  onCompletion = { result ->
    when (result) {
      is Keyless.KeylessResult.Success -> {

      	val temporaryState = result.value.temporaryState
      	// store the temporary state on your backend to recover the account in the future

      }
      is Keyless.KeylessResult.Failure -> Log.d("KeylessSDK ", "error code ${result.error.code}")
    }
  }
)

iOS

During the enrollment flow:

let enrollConfig = BiomEnrollConfig(shouldRetrieveTemporaryState: true)

Keyless.enroll(
  configuration: enrollConfig,
  onCompletion: { result in
    switch result {
    case .success(let enrollSuccess):
    	
    	let temporaryState = enrollSuccess.temporaryState
    	// store the temporary state on your backend to recover the account in the future

    case .failure(let error):
        print("error code: \(error.code)
    }
  })

During the authentication flow:

let authConfig = BiomAuthConfig(shouldRetrieveTemporaryState: true)

Keyless.authenticate(
  configuration: authConfig,
  onCompletion: { result in
    switch result {
    case .success(let authSuccess):
    	
    	let temporaryState = authSuccess.temporaryState
    	// store the temporary state on your backend to recover the account in the future

    case .failure(let error):
        print("error code: \(error.code)
    }
  })

Flutter

During the enrollment flow:

import 'package:keyless_flutter_sdk/keyless.dart';
import 'package:keyless_flutter_sdk/models/configurations/enrollment_configuration.dart';

final enrollConfig = BiomEnrollConfig(shouldRetrieveTemporaryState: true);

try {
    final result = await Keyless.instance.enroll(enrollConfig);
    if (result.temporaryState != null) {
        // store the temporary state on your backend to recover the account in the future
        print("Temporary state retrieved: ${result.temporaryState}");
    }
} catch (error) {
    print("Enrollment failed: $error");
}

During the authentication flow:

import 'package:keyless_flutter_sdk/keyless.dart';
import 'package:keyless_flutter_sdk/models/configurations/authentication_configuration.dart';

final authConfig = BiomAuthConfig(shouldRetrieveTemporaryState: true);

try {
    final result = await Keyless.instance.authenticate(authConfig);
    if (result.temporaryState != null) {
        // store the temporary state on your backend to recover the account in the future
        print("Temporary state retrieved: ${result.temporaryState}");
    }
} catch (error) {
    print("Authentication failed: $error");
}

Recover from temporary state

Pass the temporary state during the enrollment flow to recover the account. The temporary state is the one you obtained and stored securely in the previous step.

When enrolling from the temporary state, Keyless shows the authentication UI to users. In the past users already went through the enrollment "onboarding" flow, we can reduce the friction in account recovery performing the authentication flow. For technical reasons developers need to call Keyless.enroll instead of Keyless.authenticate even if the UI is the one from authentication flow.

Android

// temporaryState retrieved from previous step
val temporaryState = "<your_temporary_state>"

val enrollConfig = BiomEnrollConfig(temporaryState = temporaryState)

Keyless.enroll(
  configuration = enrollConfig,
  onCompletion = { result ->
    when (result) {
      is Keyless.KeylessResult.Success -> {

      	// account recovered
      	val userId = result.value.userId

      }
      is Keyless.KeylessResult.Failure -> Log.d("KeylessSDK ", "error code ${result.error.code}")
    }
  }
)

iOS

// temporaryState retrieved from previous step
let temporaryState = "<your_temporary_state>"

let enrollConfig = BiomEnrollConfig(temporaryState: temporaryState)

Keyless.enroll(
  configuration: enrollConfig,
  onCompletion: { result in
    switch result {
    case .success(let enrollSuccess):
    	
    	// account recovered
      	let userId = enrollSuccess.userId

    case .failure(let error):
        print("error code: \(error.code)
    }
  })

Flutter

import 'package:keyless_flutter_sdk/keyless.dart';
import 'package:keyless_flutter_sdk/models/configurations/enrollment_configuration.dart';

// temporaryState retrieved from previous step
final temporaryState = "<your_temporary_state>";

final enrollConfig = BiomEnrollConfig(temporaryState: temporaryState);

try {
    final result = await Keyless.instance.enroll(enrollConfig);
    // account recovered
    print("Account recovered successfully. UserID: ${result.keylessId}");
} catch (error) {
    print("Account recovery failed: $error");
}

The account is recovered and it's now possible to authenticate the user.