2️⃣ Enrollment

Enrollment is the process of registering a new user by connecting their facial biometrics to a Keyless account. During this process, a full and unobstructed view of the user's face is required.

SDK v5

Android

val configuration = BiomEnrollConfig()

Keyless.enroll(
  configuration = configuration,
  onCompletion = { result ->
    when (result) {
      is Keyless.KeylessResult.Success -> Log.d("KeylessSDK ", "Enroll success - userId ${result.value.keylessId}")
      is Keyless.KeylessResult.Failure -> Log.d("KeylessSDK ", "Enroll failure - error code ${result.error.code}")
    }
  }
)

iOS

let configuration = BiomEnrollConfig()

Keyless.enroll(
  configuration: configuration,
  onCompletion: { result in
    switch result {
    case .success(let enrollmentSuccess):
        print("Enrollment finished successfully. UserID: \(enrollmentSuccess.keylessId)")
    case .failure(let error):
        print("Enrollment finished with error: \(error.message)
    }
  })

Android 4.6

val configuration = EnrollmentConfiguration.builder.build()

Keyless.enroll(
  enrollmentConfiguration = configuration,
  onCompletion = { result ->
    when (result) {
      is Keyless.KeylessResult.Success -> Log.d("KeylessSDK ", "Enroll success - userId ${result.value.keylessId}")
      is Keyless.KeylessResult.Failure -> Log.d("KeylessSDK ", "Enroll failure - error code ${result.error.code}")
    }
  }
)

iOS 4.6

let configuration = Keyless.EnrollmentConfiguration.builder.build()

Keyless.enroll(
  enrollmentConfiguration: configuration,
  onCompletion: { result in
    switch result {
    case .success(let enrollmentSuccess):
        print("Enrollment finished successfully. UserID: \(enrollmentSuccess.keylessId)")
    case .failure(let error):
        print("Enrollment finished with error: \(error.message)
    }
  })

Flutter

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

final configuration = BiomEnrollConfig();

try {
  final result = await Keyless.instance.enroll(configuration);
  print("Enrollment finished successfully. UserID: ${result.keylessId}");
} catch (error) {
  print("Enrollment finished with error: $error");
}

Enrollment configuration

You can configure the enrollment process with optional parameters in your BiomEnrollConfig() instance or using the builder pattern methods from the EnrollmentConfiguration builder.

Android

public data class BiomEnrollConfig(
    public val cameraDelaySeconds: Int = 2,
    public val customSecret: String?,
    public val iamToken: String?
    public val jwtSigningInfo: JwtSigningInfo?,
    public val livenessConfiguration: LivenessSettings.LivenessConfiguration = PASSIVE_STANDALONE_HIGH,
    public val livenessTimeout: Int = 60,
    public val operationInfo: OperationInfo?,
    public val shouldRetrieveTemporaryState: Boolean = false,
    public val shouldRetrieveEnrollmentSelfie: Boolean = false,
    public val temporaryState: String?,
    public val showScreenSuccessFlow: Boolean = true,
    public val showScreenInstructions: Boolean = true,
    public val showScreenFailureFlow: Boolean = true
)

iOS

public struct BiomEnrollConfig {
    public let cameraDelaySeconds: Int
    public let customSecret: String?
    public let iamToken: String?
    public let jwtSigningInfo: JwtSigningInfo?
    public let livenessConfiguration: Keyless.LivenessConfiguration
    public let livenessTimeout: Int
    public let operationInfo: Keyless.OperationInfo?
    public let shouldRetrieveTemporaryState: Bool
    public let shouldReturnEnrollmentSelfie: Bool
    public let temporaryState: String?,
    public let showScreenSuccessFlow: Bool,
    public let showScreenInstructions: Bool,
    public let showScreenFailureFlow: Bool
}

Android 4.6

public interface EnrollmentConfigurationBuilder {

    public fun retrievingBackup(): EnrollmentConfigurationBuilder

    public fun retrievingTemporaryState(): EnrollmentConfigurationBuilder

    public fun savingSecret(customSecret: String): EnrollmentConfigurationBuilder

    public fun withBackup(backupKey: ByteArray, backupData: ByteArray): EnrollmentConfigurationBuilder

    public fun withDelay(cameraDelaySeconds: Int): EnrollmentConfigurationBuilder

    public fun withEnrollmentSelfie(): EnrollmentConfigurationBuilder

    public public fun withIAMToken(token: String)

    public fun withLivenessSettings(
        livenessConfiguration: LivenessSettings.LivenessConfiguration,
        livenessTimeout: Int
    ): EnrollmentConfigurationBuilder

    public fun withOperationInfo(
        operationId: String,
        payload: String? = null,
        externalUserId: String? = null
    ): EnrollmentConfigurationBuilder

    public fun withPin(pin: String): EnrollmentConfigurationBuilder

    public fun withTemporaryState(temporaryState: String): EnrollmentConfigurationBuilder

    public fun build(): EnrollmentConfiguration
}

iOS 4.6

public protocol EnrollmentConfigurationBuilder {

    public func retrievingBackup() -> EnrollmentConfigurationBuilder

    public func retrievingTemporaryState() -> EnrollmentConfigurationBuilder

    public func savingSecret(_ customSecret: String) -> EnrollmentConfigurationBuilder

    public func withBackup(_ backup: Keyless.Backup) -> EnrollmentConfigurationBuilder

    public func withDelay(seconds: Int) -> EnrollmentConfigurationBuilder

    public func withEnrollmentSelfie() -> EnrollmentConfigurationBuilder

    public func withIAMToken(token: String)

    public func withLivenessSettings(
        livenessConfiguration: Keyless.LivenessConfiguration,
        livenessTimeout: Int
    ) -> EnrollmentConfigurationBuilder

    public func withOperationInfo(
        id: String,
        payload: String?,
        externalUserId: String?
    ) -> EnrollmentConfigurationBuilder

    public func withPin(_ pin: String) -> EnrollmentConfigurationBuilder

    public func withTemporaryState(_ temporaryState: String) -> EnrollmentConfigurationBuilder

    public func build() -> Keyless.EnrollmentConfiguration
}

Flutter

class BiomEnrollConfig {
    final String? customSecret;
    final String? temporaryState;
    final OperationInfo? operationInfo;
    final LivenessConfiguration? livenessConfiguration;
    final int? livenessTimeout;
    final bool? shouldRetrieveTemporaryState;
    final int? cameraDelaySeconds;
    final String? iamToken;
    final JwtSigningInfo? jwtSigningInfo;
    final DynamicLinkingInfo? dynamicLinkingInfo;
    final bool? showScreenInstructions;
    final bool? showScreenSuccessFlow;
}

Enrollment success result

Depending on the builder methods you enable, Keyless will populate the corresponding fields in the EnrollmentSuccess result reported below.

Android

data class EnrollmentSuccess(
    val keylessId: String,
    val customSecret: String = "",
    val enrollmentSelfie: Bitmap? = null,
    val temporaryState: String? = null
) : KeylessSdkSuccess()

iOS

public struct EnrollmentSuccess {
    public let customSecret: String?
    public let enrollmentSelfie: CGImage?
    public let keylessId: String?
    public let temporaryState: String?
}

Flutter

class EnrollmentSuccess {
    final String keylessId;
    final String? customSecret;
    final String? temporaryState;
}

Backup data

Backup data is no longer recommended to perform account recovery and the feature has been removed from Android and iOS SDKs. Use the temporary state instead. Follow the guide on account recovery.

Keyless can generate backup data that you can use to recover an account.

To create the backup data use the shouldRetrieveBackup method. Once the enrollment succeeds, copy the backup data from the EnrollmentSuccess result, and store it securely.

To recover an account, use the backup parameter more in backup.

Camera Delay

Use cameraDelaySeconds to specify the delay (in seconds) between when the camera preview appears, and when the liveness processing starts.

Custom secret

During enrollment you can specify a custom secret to be saved and encrypted along with the user's biometric data using savingSecret paramter. The custom secret can be anything you can save as an ASCII string, such as a secret that you have provided to the app from the backend, the seed of an OTP protocol, or anything else.

Enrollment Selfie

Using shouldRetrieveEnrollmentSelfie you can retrieve the image that Keyless uses to computes the facial biometrics of the user. The image can be found in the EnrollmentSuccess result as enrollmentSelfie.

IAM Token

Specifying an iamToken you can authenticate with your IAM System, follow the guide authenticating in auth0 with Keyless

JWT Signing info

You can specify a payload to be added to a JWT signed by Keyless with the jwtSigningInfo parameter, more in JWT signing.

Liveness Settings

Using livenessConfiguration you can configure the liveness security level during enrollment. The possible liveness configuration are under LivenessSettings.LivenessConfiguration :

PASSIVE_STANDALONE_MEDIUM
PASSIVE_STANDALONE_HIGH        //recommended configuration
PASSIVE_STANDALONE_HIGHEST

You can also specify a livenessTimeout (in seconds) to cancel the enrollment if the liveness takes longer than the timeout.

More details on liveness in the dedicated liveness settings section.

Operation info

The parameter operationInfo specifies a customizable unique operation identifier and associated payload stored on the Keyless backend if the enrollment succeeds. Use this to add an extra level of confirmation in your operations.

Details on how to query our backend for stored operations are available on Operations API.

Temporary State

Keyless users can be enrolled via IDV-Bridge, Identity Verification Bridge. As a result of IDV-Bridge enrollment you receive a temporary state useful to register users in your app without undergoing the full enrollment flow.

Use the temporaryState parameter to register users from a temporary state obtained through IDV-Bridge or follow the account recovery guide.

SDK v4

Android

val configuration = BiomEnrollConfig()

Keyless.enroll(
  configuration = configuration,
  onCompletion = { result ->
    when (result) {
      is Keyless.KeylessResult.Success -> Log.d("KeylessSDK ", "Enroll success - userId ${result.value.keylessId}")
      is Keyless.KeylessResult.Failure -> Log.d("KeylessSDK ", "Enroll failure - error code ${result.error.code}")
    }
  }
)

iOS

let configuration = BiomEnrollConfig()

Keyless.enroll(
  configuration: configuration,
  onCompletion: { result in
    switch result {
    case .success(let enrollmentSuccess):
        print("Enrollment finished successfully. UserID: \(enrollmentSuccess.keylessId)")
    case .failure(let error):
        print("Enrollment finished with error: \(error.message)
    }
  })

Android 4.6

val configuration = EnrollmentConfiguration.builder.build()

Keyless.enroll(
  enrollmentConfiguration = configuration,
  onCompletion = { result ->
    when (result) {
      is Keyless.KeylessResult.Success -> Log.d("KeylessSDK ", "Enroll success - userId ${result.value.keylessId}")
      is Keyless.KeylessResult.Failure -> Log.d("KeylessSDK ", "Enroll failure - error code ${result.error.code}")
    }
  }
)

iOS 4.6

let configuration = Keyless.EnrollmentConfiguration.builder.build()

Keyless.enroll(
  enrollmentConfiguration: configuration,
  onCompletion: { result in
    switch result {
    case .success(let enrollmentSuccess):
        print("Enrollment finished successfully. UserID: \(enrollmentSuccess.keylessId)")
    case .failure(let error):
        print("Enrollment finished with error: \(error.message)
    }
  })

Flutter

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

final configuration = BiomEnrollConfig();

try {
  final result = await Keyless.instance.enroll(configuration);
  print("Enrollment finished successfully. UserID: ${result.keylessId}");
} catch (error) {
  print("Enrollment finished with error: $error");
}

Enrollment configuration

You can configure the enrollment process with optional parameters in your BiomEnrollConfig() instance or using the builder pattern methods from the EnrollmentConfiguration builder.

Android

public data class BiomEnrollConfig(
    public val cameraDelaySeconds: Int = 2,
    public val customSecret: String?,
    public val iamToken: String?
    public val jwtSigningInfo: JwtSigningInfo?,
    public val livenessConfiguration: LivenessSettings.LivenessConfiguration = PASSIVE_STANDALONE_HIGH,
    public val operationInfo: OperationInfo?,
    public val shouldRetrieveTemporaryState: Boolean = false,
    public val shouldRetrieveEnrollmentSelfie: Boolean = false,
    public val temporaryState: String?,
    public val showScreenSuccessFlow: Boolean = true,
    public val showScreenSuccessFaceCapture: Boolean = true,
    public val showScreenInstructions: Boolean = true
)

iOS

public struct BiomEnrollConfig {
    public let cameraDelaySeconds: Int
    public let customSecret: String?
    public let iamToken: String?
    public let jwtSigningInfo: JwtSigningInfo?
    public let livenessConfiguration: Keyless.LivenessConfiguration
    public let operationInfo: Keyless.OperationInfo?
    public let shouldRetrieveTemporaryState: Bool
    public let shouldReturnEnrollmentSelfie: Bool
    public let temporaryState: String?,
    public let showScreenSuccessFlow: Bool,
    public let showScreenSuccessFaceCapture: Bool,
    public let showScreenInstructions: Bool
}

Android 4.6

public interface EnrollmentConfigurationBuilder {

    public fun retrievingBackup(): EnrollmentConfigurationBuilder

    public fun retrievingTemporaryState(): EnrollmentConfigurationBuilder

    public fun savingSecret(customSecret: String): EnrollmentConfigurationBuilder

    public fun withBackup(backupKey: ByteArray, backupData: ByteArray): EnrollmentConfigurationBuilder

    public fun withDelay(cameraDelaySeconds: Int): EnrollmentConfigurationBuilder

    public fun withEnrollmentSelfie(): EnrollmentConfigurationBuilder

    public public fun withIAMToken(token: String)

    public fun withLivenessSettings(
        livenessConfiguration: LivenessSettings.LivenessConfiguration,
        livenessTimeout: Int
    ): EnrollmentConfigurationBuilder

    public fun withOperationInfo(
        operationId: String,
        payload: String? = null,
        externalUserId: String? = null
    ): EnrollmentConfigurationBuilder

    public fun withPin(pin: String): EnrollmentConfigurationBuilder

    public fun withTemporaryState(temporaryState: String): EnrollmentConfigurationBuilder

    public fun build(): EnrollmentConfiguration
}

iOS 4.6

public protocol EnrollmentConfigurationBuilder {

    public func retrievingBackup() -> EnrollmentConfigurationBuilder

    public func retrievingTemporaryState() -> EnrollmentConfigurationBuilder

    public func savingSecret(_ customSecret: String) -> EnrollmentConfigurationBuilder

    public func withBackup(_ backup: Keyless.Backup) -> EnrollmentConfigurationBuilder

    public func withDelay(seconds: Int) -> EnrollmentConfigurationBuilder

    public func withEnrollmentSelfie() -> EnrollmentConfigurationBuilder

    public func withIAMToken(token: String)

    public func withLivenessSettings(
        livenessConfiguration: Keyless.LivenessConfiguration,
        livenessTimeout: Int
    ) -> EnrollmentConfigurationBuilder

    public func withOperationInfo(
        id: String,
        payload: String?,
        externalUserId: String?
    ) -> EnrollmentConfigurationBuilder

    public func withPin(_ pin: String) -> EnrollmentConfigurationBuilder

    public func withTemporaryState(_ temporaryState: String) -> EnrollmentConfigurationBuilder

    public func build() -> Keyless.EnrollmentConfiguration
}

Flutter

class BiomEnrollConfig {
    final String? customSecret;
    final String? temporaryState;
    final OperationInfo? operationInfo;
    final LivenessConfiguration? livenessConfiguration;
    final int? livenessTimeout;
    final bool? shouldRetrieveTemporaryState;
    final int? cameraDelaySeconds;
    final String? iamToken;
    final JwtSigningInfo? jwtSigningInfo;
    final DynamicLinkingInfo? dynamicLinkingInfo;
    final bool? showScreenInstructions;
    final bool? showScreenSuccessFaceCapture;
    final bool? showScreenSuccessFlow;
}

Enrollment success result

Depending on the builder methods you enable, Keyless will populate the corresponding fields in the EnrollmentSuccess result reported below.

Android

data class EnrollmentSuccess(
    val keylessId: String,
    val customSecret: String = "",
    val enrollmentSelfie: Bitmap? = null,
    val temporaryState: String? = null
) : KeylessSdkSuccess()

iOS

public struct EnrollmentSuccess {
    public let customSecret: String?
    public let enrollmentSelfie: CGImage?
    public let keylessId: String?
    public let temporaryState: String?
}

Flutter

class EnrollmentSuccess {
    final String keylessId;
    final String? customSecret;
    final String? temporaryState;
}

Backup data

Backup data is no longer recommended to perform account recovery and the feature has been removed from Android and iOS SDKs. Use the temporary state instead. Follow the guide on account recovery.

Keyless can generate backup data that you can use to recover an account.

To create the backup data use the shouldRetrieveBackup method. Once the enrollment succeeds, copy the backup data from the EnrollmentSuccess result, and store it securely.

To recover an account, use the backup parameter more in backup.

Camera Delay

Use cameraDelaySeconds to specify the delay (in seconds) between when the camera preview appears, and when the liveness processing starts.

Custom secret

During enrollment you can specify a custom secret to be saved and encrypted along with the user's biometric data using savingSecret paramter. The custom secret can be anything you can save as an ASCII string, such as a secret that you have provided to the app from the backend, the seed of an OTP protocol, or anything else.

Enrollment Selfie

Using shouldRetrieveEnrollmentSelfie you can retrieve the image that Keyless uses to computes the facial biometrics of the user. The image can be found in the EnrollmentSuccess result as enrollmentSelfie.

IAM Token

Specifying an iamToken you can authenticate with your IAM System, follow the guide authenticating in auth0 with Keyless

JWT Signing info

You can specify a payload to be added to a JWT signed by Keyless with the jwtSigningInfo parameter, more in JWT signing.

Liveness Settings

Using livenessConfiguration you can configure the liveness security level during enrollment. The possible liveness configuration are under LivenessSettings.LivenessConfiguration :

PASSIVE_STANDALONE_MEDIUM
PASSIVE_STANDALONE_HIGH        //recommended configuration
PASSIVE_STANDALONE_HIGHEST

You can also specify a livenessTimeout (in seconds) to cancel the enrollment if the liveness takes longer than the timeout.

The liveness timeout customization has been deprecated in both Android and iOS SDKs. If you’re still using it, please note that it’s no longer effective.

More details on liveness in the dedicated liveness settings section.

Operation info

The parameter operationInfo specifies a customizable unique operation identifier and associated payload stored on the Keyless backend if the enrollment succeeds. Use this to add an extra level of confirmation in your operations.

Details on how to query our backend for stored operations are available on Operations API.

Temporary State

Keyless users can be enrolled via IDV-Bridge, Identity Verification Bridge. As a result of IDV-Bridge enrollment you receive a temporary state useful to register users in your app without undergoing the full enrollment flow.

Use the temporaryState parameter to register users from a temporary state obtained through IDV-Bridge or follow the account recovery guide.