The diagrams below show how the Keyless SDK, which runs within your mobile app on the user’s device, interacts with your application server and with the Keyless network.

Enrollment

During enrollment, your mobile app invokes the enroll method from the Keyless SDK, and then:

1. Guides the user through capturing a biometric signal with the device camera.

2. Interacts with Keyless to generate a new user identifier (Keyless ID), which is then returned to your mobile app.

Authentication

Authentication involves your application server, your mobile app, and the Keyless network, as depicted in Figure 2:

1. This process starts when the user performs an action that requires authentication using your mobile app.

2. The app provides the details of this action to your application server, which generates a challenge. The challenge is sent to the mobile app, which uses the Keyless SDK to compute the corresponding authentication token using the authenticate method.

3. The Keyless SDK authenticates the user by capturing the user’s biometrics using the mobile device’s camera.

4. The Keyless SDK connects to the Keyless network, and runs a secure multi-party computation protocol that authenticates the user and generates the authentication token in response to the challenge provided in Step 2. The Keyless SDK returns the authentication token to the mobile app.

5. The app sends the token to your application server, which verifies it.

6. If the authentication token is valid, the application server completes the transaction and notifies your mobile app.

Account Deletion

Account deletion is similar to authentication. First, your mobile app performs authentication steps 1-6, then it notifies your application server that the user wants to delete the account. Next, your mobile app invokes the deEnroll method from the Keyless SDK. This method issues a deletion request to the Keyless network (Step 7). The request removes all data associated with the user from the Keyless network.

In order to introduce Keyless to users before the very first enrollment, it may be helpful to show an explanatory screen on what is the flow about to start.

This screen is showable via the public API Keyless.showIntroductionScreen. This function can be called at any moment (even before setup). It expects a completion for when the user taps on the main CTA. The message can be customized as explained in UI-Customization

Examples

Keyless.showIntroductionScreen { 
    // Perform actions after user taps CTA
}

Keyless.showIntroductionScreen { 
    // Perform actions after user taps CTA
}

De-enrollment is the biometric equivalent of an account deletion. Keyless performs an to compare the user's facial biometrics with the ones computed during . If the biometrics match, the user is authenticated and their account will be removed from Keyless. This operation is irreversible.

DeEnrollment configuration

Camera Delay

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

Success Feedback

Use showSuccessFeedback to show a Success text on top of the screen when the DeEnroll is successful.

Liveness Settings

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

You can also specify a livenessEnvironmentAware that is by default se to true to enhance liveness detection. This parameters helps to ensure the user is in a suitable setting for verification.

More details on liveness in the dedicated section.

The Keyless SDK "caches" the enrolled user locally on the device.

There are some use cases where it is possible to and . The Keyless SDK will not be notified about such deletions. For this reason if you try to authenticate a user or a device that have been deleted from server API you will get an error.

Call validateUserAndDeviceActive before authenticating, to validate that both the user and the device are still active in the Keyless backend, to avoid asking the user for biometric data which will still not let them authenticate.

User identifier

Retrieve the user identifier with Keyless.getUserId():

Device identifier

The device is identified by its public signing key. To retrieve the public signing key use Keyless.getDevicePublicSigningKey():

Keyless SDK reset

Resetting the Keyless SDK to a clean state deletes local data from the device, but does not de-enoll the user from the Keyless backend or deactivate the device from the Keyless backend:

Lockout management

The getRateLimitInfo API checks whether the user is currently rate-limited and, if so, for how many seconds. This API is typically used to provide feedback to users after multiple failed authentication attempts.

Introduction

Learn how the Keyless SDK components can be integrated into a mobile application and backend server, to enable biometric authentication.

Integration Overview

Enrollment Flow

To authenticate with Keyless, a user must first enroll their biometric template. Enrollment with Keyless consists of registering the user’s biometric features in a privacy-preserving manner using the various from the Keyless SDK.

Authentication Flow

The most common authentications scenarios for the Keyless SDK are:

• access to a web application

• access on a mobile application

Authentication in a web application

In this scenario the user is trying access to a resource in a web application for which strong authentication is required. The web application backend sends a push notification to the customer app to request that the user identify themselves with Keyless. After biometric authentication is successful, the flow returns to the web application backend, which leverages the APIs exposed by the Keyless backend to perform additional security checks.

Once the Keyless backend confirms that the authentication was successful, the user is allowed access to the resource.

Authentication on a mobile app

In this scenario the user is trying access to a resource directly in the mobile application for which strong authentication is required. The mobile application sends a push notification to the customer app to request that the user identify themselves with Keyless. After biometric authentication is successful, the flow returns to the mobile application backend, which leverages the APIs exposed by the Keyless backend to perform additional security checks.

Once the Keyless backend confirms that the authentication was successful, the user is allowed access to the resource.

Keyless Components

As mentioned, Keyless is composed of two main blocks:

• Keyless SDK

• Keyless backend / Confirmation API Service

Keyless SDK

The Keyless SDK supports both Android and iOS, and exposes API methods to interact with the Keyless Privacy-Preserving Network to perform the following actions:

• Enroll a user

• Authenticate

• De-Enroll

• Restore backup

Keyless backend

The Keyless SaaS backend offers APIs which can be used to perform security checks through Backend-to-Backend calls. Specifically, it is possible to interrogate the Keyless Backend after the SDK returns an OK response for an Authentication attempt.

Keyelss mobile SDK can generate a signed a JWT containing a custom payload. You can use the signed JWT to implement .

Generate signed JWT

Pass JwtSigningInfo to the authentication to generate a signed JWT:

User signing public key

The AuthenticationSuccess contains the following fields:

• signedJwt: the signed JWT.

What is Account Recovery?

Account Recovery is the term we use to describe the use case where a user is known to our customer (i.e. is registered in Keyless), but needs to be authenticated on a new device. Typically this is either where:

• They had previously been enrolled on a device but the user no longer has access to it.

• They are adding a back-up device.

• They are known to our customer, perhaps having submitted a selfie during onboarding, but have yet to authenticate on a device via our Mobile SDK within our customer's app (which would have to leverage ).

Client or Temporary State

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

The client or temporary state is obtained:

1. From your backend through Keyless IDVBridge.

   • To understand how to generate this state see our or

   • Then head to to understand how to leverage this state to bind a userID to a new device.

2. From your client app using the Keyless Mobile SDK:

   • during live enrollment or authentication.

   • Then head to to understand how to leverage this state to bind a userID to a new device.

Liveness Configuration

Keyless SDK provides three officially-supported configurations for the liveness detection (antispoofing component), listed below from the lowest to the highest level of security:

• PASSIVE_STANDALONE_MEDIUM - for testing purposes only

• PASSIVE_STANDALONE_HIGH - for most production use (SDK default)

• PASSIVE_STANDALONE_HIGHEST - for higher security production use

Increasing the security level increases the ability of the system to reject spoof attempts (true positive rate, or TPR). A higher security level also increases the genuine reject rate (false positive rate, or FPR) and the time required by the anti-spoofing module to make a decision.

For most production scenarios, Keyless recommends the use of PASSIVE_STANDALONE_HIGH. This setting offers a good tradeoff between TPR, FPR, and time-to-decision. For scenarios that require a higher security level, we recommend increasing this setting to PASSIVE_STANDALONE_HIGHEST.

Liveness Awareness

You can also specify a livenessEnvironmentAware that is by default se to true to enhance liveness detection. This parameters helps to ensure the user is in a suitable setting for verification.

Note that we have observed that this may prevent some users on a very limited set of devices from authenticating with Keyless. In this case the SDK will return an 20021 error.

Relax liveness checks for testing purposes

Below follows a liveness configuration example for testing pruposes only should facilitate testing the happy path of "passing the liveness checks".

// ONLY FOR TEST

// Authentication Configuration
val authConfig = BiomAuthConfig(
        livenessConfiguration = LivenessSettings.LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM,
        livenessEnvironmentAware = false
)


// Enrollment Configuration
val enrollConfig = BiomEnrollConfig(
        livenessConfiguration = LivenessSettings.LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM,
        livenessEnvironmentAware = false
)


// De-Enrollment Configuration
val deEnrollConfig = BiomDeEnrollConfig(
        livenessConfiguration = LivenessSettings.LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM,
        livenessEnvironmentAware = false
)

// ONLY FOR TEST

// Authentication Configuration
let authConfig = BiomAuthConfig(
        livenessConfiguration: Keyless.LivenessConfiguration.passiveStandaloneMedium
        livenessEnvironmentAware: false
)

// Enrollment Configuration
let enrollConfig = BiomEnrollConfig(
        livenessConfiguration: Keyless.LivenessConfiguration.passiveStandaloneMedium
        livenessEnvironmentAware: false
)

// De-Enrollment Configuration
let deEnrollConfig = BiomDeEnrollConfig(
        livenessConfiguration: Keyless.LivenessConfiguration.passiveStandaloneMedium
        livenessEnvironmentAware: false
)

// ONLY FOR TEST


// Authentication Configuration
final authConfig = BiomAuthConfig(
    livenessConfiguration: LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM
    // livenessEnvironmentAware: false - not available yet
);

// Enrollment Configuration
final enrollConfig = BiomEnrollConfig(
    livenessConfiguration: LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM
    // livenessEnvironmentAware: false - not available yet

);

// De-Enrollment Configuration
final deEnrollConfig = BiomDeEnrollConfig(
    livenessConfiguration: LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM
    // livenessEnvironmentAware: false - not available yet
);

What is the temporary state?

The Keyless temporary state (referred to as the client state in other contexts) contains all the necessary information to restore an account. It can be created during enrollment and authentication

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.

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)
    }
  })

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)
    }
  })

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");
}

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");
}

Operations

JWT

The Keyless SDK uses three classes of errors, each error has an error code and an error message. Errors follow 3 main categories:

• Internal errors: triggered by Keyless internals.

• Integration errors: triggered by a KeylessSDK integration misconfiguration.

• User errors: triggered by unintended user behavior.

If you're implementing the Keyless SDK, you should handle errors coming from the SDK since the error message is not intended for end users.

Internal errors

Internal errors have code that are lower than 20_000. Internal errors require investigation from Keyless. If errors persist, please keep the error code, error message and stacktrace and contact us.

Integration errors

Integration errors have codes that span from 20_000 to 30_000. Integration errors can be solved by making sure you are not misusing the API surface of the SDK. You can solve it by reading the error message and addressing the issue. If errors persist, please keep the error code, error message and stacktrace and contact us.

User errors

User errors have code that are higher than 30_000. Intergration errors have code between 20_000 and 30_000.

Examples

val configuration = Keyless.AuthenticationConfiguration()

Keyless.authenticate(
    authenticationConfiguration = configuration,
    onCompletion = { result ->
        when (result) {
            is Keyless.KeylessResult.Success -> {
                Log.d("IntegratorActivity ", "Authenticate success")
            }
            is Keyless.KeylessResult.Failure -> {
                when (result.error) {
                    is KeylessUserError.FaceNotMatching -> Log.d("IntegratorActivity ", "Face not matching")
                    is KeylessUserError.MaskDetected -> Log.d("IntegratorActivity ", "Mask detected")
                    is KeylessUserError.Spoofing -> Log.d("IntegratorActivity ", "Spoofing detected")
                    is KeylessUserError.Timeout -> Log.d("IntegratorActivity ", "The operation timed out")
                    is KeylessUserError.UserCancelled -> Log.d("IntegratorActivity ", "The user cancelled the operation")
                    is KeylessUserError.NoNetworkConnection -> Log.d("IntegratorActivity ", "No network connection available")
                    is KeylessUserError.Lockout -> Log.d("IntegratorActivity ", "Your account is temporarily locked")
                    else -> {
                        Log.d("IntegratorActivity ", "Authenticate failure")

                        val errorCode = result.error.code
                        val errorMessage = result.error.message
                        val errorCause = result.error.cause?.printStackTrace()
                        // here you could display a generic error popup with the error code
                    }
                }
            }
        }
    }
)

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

Keyless.authenticate(authenticationConfiguration: configuration) { result in
    switch result {
    case .success(let authenticationSuccess):
        print("authenticationDidFinish:  \(authenticationSuccess.token)")
    case .failure(let error):
        switch error.kind {
        case .userError(let userError):
            switch userError {
            case .faceNotMatching:
                print("Face not matching")
            case .maskDetected:
                print("Mask detected")
            case .spoofing:
                print("Spoofing detected")
            case .timeout:
                print("The operation timed out")
            case .userCancelled:
                print("The user cancelled the operation")
            case .noNetworkConnection:
                print("No network connection available")
            case .lockout:
                print("Your account is temporarily locked")
            }
        default:
            let code = error.code
            let message = error.message
            // here you could display a generic error popup with the error code
        }
    }
}

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

final configuration = BiomAuthConfig();

try {
  final result = await Keyless.instance.authenticate(configuration);
  print("Authentication successful");
} catch (error) {
  if (error is KeylessError) {
    switch (error.errorType) {
      case KeylessErrorType.user:
        if (error.code == KeylessErrorCase.faceNotMatching.code) {
          print("Face not matching");
        } else if (error.code == KeylessErrorCase.maskDetected.code) {
          print("Mask detected");
        } else if (error.code == KeylessErrorCase.spoofing.code) {
          print("Spoofing detected");
        } else if (error.code == KeylessErrorCase.timeout.code) {
          print("The operation timed out");
        } else if (error.code == KeylessErrorCase.userCancelled.code) {
          print("The user cancelled the operation");
        } else if (error.code == KeylessErrorCase.noNetworkConnection.code) {
          print("No network connection available");
        } else if (error.code == KeylessErrorCase.deviceTampered.code) {
          print("Device security check failed");
        } else if (error.code == KeylessErrorCase.lockout.code) {
          print("Your account is temporarily locked");
        }
        break;
      default:
        // Handle internal or integration errors
        print("Authentication failed: ${error.message} (Code: ${error.code})");
        // Here you could display a generic error popup with the error code
    }
  }
}

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.

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}")
    }
  }
)

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)
    }
  })

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}")
    }
  }
)

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)
    }
  })

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.

public data class BiomEnrollConfig(
    public val cameraDelaySeconds: Int = 2,
    public val customSecret: String?,
    public val jwtSigningInfo: JwtSigningInfo?,
    public val livenessConfiguration: LivenessSettings.LivenessConfiguration = PASSIVE_STANDALONE_HIGH,
    public val livenessEnvironmentAware: Boolean = true,
    public val operationInfo: OperationInfo?,
    public val shouldRetrieveTemporaryState: Boolean = false,
    public val shouldRetrieveEnrollmentFrame: Boolean = false,
    public val temporaryState: String?,
    public val showSuccessFeedback: Boolean = true,
    public val showInstructionsScreen: Boolean = true,
    public val showFailureFeedback: Boolean = true
)

public struct BiomEnrollConfig {
    public let cameraDelaySeconds: Int
    public let customSecret: String?
    public let jwtSigningInfo: JwtSigningInfo?
    public let livenessConfiguration: Keyless.LivenessConfiguration
    public let livenessEnvironmentAware: Bool
    public let operationInfo: Keyless.OperationInfo?
    public let shouldRetrieveTemporaryState: Bool
    public let shouldReturnEnrollmentFrame: Bool
    public let temporaryState: String?,
    public let showSuccessFeedback: Bool,
    public let showInstructionsScreen: Bool,
    public let showFailureFeedback: Bool
}

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 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
}

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 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
}

class BiomEnrollConfig {
    final String? customSecret;
    final String? temporaryState;
    final OperationInfo? operationInfo;
    final LivenessConfiguration? livenessConfiguration;
    final int? livenessTimeout;
    final bool? shouldRetrieveTemporaryState;
    final int? cameraDelaySeconds;
    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.

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

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

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

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.

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 livenessEnvironmentAware that is by default se to true to enhance liveness detection. This parameters helps to ensure the user is in a suitable setting for verification.

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.

You can also use a temporary state to recover an account of an existing user who lost access to the account. Follow the guide on account recovery.

Enrollment Frame

Integrators can specify whether or not to retrieve an enrollment frame, acquired during the user’s selfie capture during the enrollment or account recovery flow. You can achieve this by setting shouldReturnEnrollmentFrame to true on the BiomEnrollmentConfig (defaults to false). If the enrollment succeeds, you can retrieve the frame from the returned EnrollmentSuccess, via enrollmentFrame.

Recover from temporary state

Pass the temporary state created during the enrollment flow or via IDV Bridge to recover the account on a new device. The temporary state is the one you obtained and stored securely when enrolling users via IDV Bridge or the Mobile SDK on the previous sub-page

// 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}")
    }
  }
)

// 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)
    }
  })

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 with ongoing 2 factor authentication with a single

Authentication is the biometric equivalent of "signing-in". During authentication Keyless compares the user's facial biometrics with the ones computed during .

If the biometrics match, Keyless authenticates the user.

Authentication configuration

You can configure the authentication process with optional parameters in your BiomAuthConfig() instance or using the builder pattern methods from the AuthenticationConfiguration builder.

Authentication success result

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

Backup data

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

To create the backup data use the shouldRetrieveBackup configuration parameter. Once authentication succeeds, copy the backup data from the AuthenticationSuccess result, and store it securely.

To recover an account, use backup parameter during enrollment more in .

Camera Delay

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

Custom Secret

If you saved a custom secret during , you can retrieve it using the shouldRetrieveSecret parameter.

Keyless will populate the field customSecret in the AuthenticationSuccess result.

Furthermore, such a custom secret can be deleted using the shouldDeleteSecret parameter.

JWT Signing info

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

Liveness Settings

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

You can also specify a livenessEnvironmentAware that is by default se to true to enhance liveness detection. This parameters helps to ensure the user is in a suitable setting for verification.

More details on liveness in the dedicated section.

Operation info

The parameter operationInfo specifies a customizable unique operation identifier and associated payload stored on the Keyless backend if the enrollment succeeds.

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

Temporary State

Use the shouldRetrieveTemporaryState parameter to creata a temporary state useful for the .

As introduce in the :

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.

If you possess a trusted source, such as an identity document, Keyless allows you to register a new user connecting their facial biometric from the identity document photo. The assumption behind the feature is that the identity document photo fulfills the requirement of a full and unobstructed view of the user's face.

To enroll a user from the photo use the PhotoEnrollConfig.

Photo Enrollment configuration

You can configure the enrollment process with optional parameters in your PhotoEnrollConfig() instance.

Photo Enrollment success result

If the Enroll from photo is successful you will find in the EnrollmentSuccess containing the corresponding fields you requested during configuration.

If the enrollment is successful the user is enrolled and can with Keyless from now on.

To embed privacy-preserving biometric authentication in your mobile applications:

Next steps

• Learn about user and device management with the .

• Learn about user and device management with the .

Back up your user's data so you can restore their Keyless account when necessary.

Create a backup (not recommended)

Create backups after authentication, and push them into your backup system. Each backup is encrypted with aes-gcm using the backupKey as symmetric key. You need both backupData and backupKey to restore an account with Keyless.

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

// Retrieve temporary state during authentication
final configuration = BiomAuthConfig(shouldRetrieveTemporaryState: true);

try {
    final result = await Keyless.instance.authenticate(configuration);
    if (result.temporaryState != null) {
        print("Temporary state retrieved successfully");
        // Store temporaryState securely
    }
} catch (error) {
    print("Failed to retrieve temporary state: $error");
}

Restore from a backup (not recommended)

Restore the user account by providing backupData and backupKey to the withBackup method:

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

// Create enrollment configuration with backup
final configuration = BiomEnrollConfig(
    backup: KeylessBackup(
        data: backupData,
        key: backupKey
    )
);

try {
    final result = await Keyless.instance.enroll(configuration);
    print("Enrollment from backup successful");
} catch (error) {
    print("Enrollment from backup failed: $error");
}

Keyless has created sample apps in both Android and iOS as companions to the official documentation. This effectively shows our SDKs working inside a basic application that can perform both Enrollment and Authentication flows.

This supports:

• Developers who want to integrate and use the Keyless Mobile SDK in their apps, by allowing them to see the SDK functioning inside a working app or emulator.

• A working demonstration of our SDK to see it in action.

The below links will launch the relevant github pages in a new tab:

• Android sample app

• iOS sample app

You can leverage the Keyless authentication mechanism to sign unrelated transactions, including Strong customer authentication (SCA) transactions.

Payment service providers compliant with are required to:

• Generate an authentication code specific to the amount of the payment transaction and the payee agreed to by the payer when initiating the transaction

• Make the payer aware of the amount of the payment transaction, and of the payee

Keyless helps you by:

• protecting the authentication code that you use for dynamic linking.

• displaying and signing the information to make the payer aware of details of the transaction.

Strong customer authentication (SCA)

By adding Keyless to your checkout flow you also benefit from .

SCA requires authentication to use at least two of the following three elements.

• Something that only the customer knows. For example, a password or PIN.

• Something that only the customer has. For example, a mobile phone or hardware token.

• Something that the customer is. For example, a biometric such as a fingerprint or face.

With Keyless Passwordless MFA you can satisfy the last two points from the list above.

SCA Compliant Dynamic Linking

The following sections contain some examples on implementing SCA with Keyless.

Display transaction information

Keyless displays a screen containing a list of labels and associated information on your behalf. For this reason, the format of the dynamicLinkingInfo must be a jsonArray containing jsonObjects (key/value pairs). We expect a valid JSON as follows:

This information is added to the Authentication request that the user needs to approve.

SCA tied to the authentication code

Once the user approves the transaction data, Keyless starts the authentication to:

1. Authenticate the payer with the device factor and the biometric factor using Keyless MFA.

2. Tie the transaction data to the Keyless MFA

To tie the transaction data to the Keyless MFA, populate the parameter dynamicLinkingInfo of the authentication configuration AuthConfig. Add the authentication code or any other information you want to display to the user and sign with Keyless MFA. For example, add the "authentication code".

Keyless can produce a signed JWT containing a claim titled td (transaction data) that contains the payload you passed as dynamicLinnkingInfo.

Verify the transaction

If the authentication is successful, the AuthenticationSuccess contains the following fields:

• signedJwt: the signed JWT (specs below).

Verify the JWT using the public key from .

Congrats, you just performed a Strong Customer Authentication displaying and signing the transaction information.

The server API has end points for automating aspects of your Keyless setup:

• List and revoke

• Remove

• Perform extra backend to backend security

API Access

• All API endpoints require the X-Api-Key: <SECRET_API_KEY> header with your security key

• All API endpoints are available at https://api.keyless.io

For a seamless SDK integration make sure to follow the section getting started.

5.1.0 - release candidate

Highlights

• Enrollment Frame: Integrators can specify whether or not to retrieve an enrollment frame, acquired during the user’s selfie capture during the enrollment or account recovery flow. See details in Enrollment Frame section.

• Enhanced Anti Inject: this release introduces a variant for enhanced frames injection prevention available to selected customers.

5.0.5 iOS - 5.0.6 Android

Highlights

• Environment-Aware Liveness Detection: a new, optional check has been introduced to enhance liveness detection helping to ensure the user is in a suitable setting for verification. This feature is enabled by default. To disable it, set livenessEnvironmentAware = false in the configuration for enrollment, authentication, or de-enrollment. See details in Liveness Settings section.

• Face Occlusion Detection for Enrollment: during the enrollment process, the SDK now provides immediate feedback to the user if their face is partially covered. A message, "Make sure your face is clearly visible," will be displayed to guide them..

Fixes

• Improved Error Handling for Temporary States: the SDK now returns a more specific internal error (error code: 539) if the maximum number of temporary states is reached during an operation.

• Added a Cancellation Button to the Camera View: an "x" button has been added to the top-left corner of the camera screen during enrollment, allowing users to safely cancel the face scan process.

5.0.3

Highlights

• Enroll from photo preview: This feature introduces the ability to enroll users using a photo provided from a trusted source.

  • Developer Responsibility: You are responsible for ensuring that the photo originates from a verified and trusted source (e.g., an official identity document).

  • Security Note: Exposing this functionality to your end-users without rigorous verification of the photo's origin may introduce vulnerabilities, such as a user enrolling with another individual's facial image. Please implement appropriate safeguards.

Enhancement: biometric processing

• Improved biometric performance through optimizations in frame timestamp processing.

5.0.1

Highlights

• New Enrollment UX: a freshened up, new User Interface has been implemented and made available.

  • It now displays real-time feedback about the quality of the processed image, allowing users to address the issues based on the messages shown during face capture.

    • Note these messages are not customizable since they are tied to Keyless image processing.

  • The temporary state now displays the enrollment UI. The change means that users will experience an onboarding flow as for plain enrollment (withtout temporary state).

    • This change was made based on customer feedback in recognition of the fact that some users will be experiencing Keyless for the first time, specifically if they were enrolled via IDV Bridge.

  • The UI differences are reported in the tab SDK v5 from the UI customization section.

• Fixes in this release

  • Added showScreenFailureFlow for consistency with the happy path showScreenSuccessFlow. By default the SDK shows an error screen for unhappy paths but the caller app can opt-out from this default behavior.

  • Return an error if camera permission is not granted. Keyless prompts the user for camera permission and now also informs the caller app that permission was not granted returning the error 30009 - camera denied .

    • See user errors for details of this and all other errors.

Improved error handling and information

Integrators familiar with our error handling documentation will notice that we have:

• Added more detailed insight and guidance for the different types of errors and the relevant error code ranges for integrators to be aware of.

• More clearly laid out the different types of User Errors with their codes & descriptions.

• "Rejected" error - we have split out instances where Liveness could not be established into a new "Rejected" error. Previously these were all labelled as "Spoofing" errors, however we recognized that in some instances these incorrectly added a framed the authentication attempt as more malicious than was fair. Please note, the guidance remains that all modelling is in some way predictive and thefore we would still advise that "Spoofing" does not guarantee that there was malicious intent and for various reasons it's still better to assume positive intent in how you handle these with users.

SDK Size Reduction

Following customer feedback, we have reduced the size of the biometric libraries which has reduced both the iOS and Android SDK integration and download size. Please note that integration size can vary significantly between customers so please contact us if you have questions in this area.

Support for iOS emulator

The Keyless iOS SDK can now be run on an iOS emulator on both Windows PC or Mac, allowing integrators to achieve faster develop and test cycles as they make changes.

Deprecations

• Liveness timeout no longer has effect and will be removed in future releases.

  • This change was made given a set of comprehensive improvements to the Liveness biometrics models. We plan to support configuration options to support both faster and slower authentication and enrollment experiences in upcoming releases.

• The mobile SDK Lockout policy, which had some reported inconsistencies, is now managed on the backend so no longer has an effect and will be removed in future releases.

  • This change was implemented based on customer feedback and done in conjunction with other changes:

    • Client side errors (example Liveness failures) now are sent to the server side and will impact the server side policy.

    • The server side policy can now be configured per customer tenant (max failed attempts, time period, suspension period). Speak to the Keyless team if you would like to review and change your lockout policy.

Breaking changes

• With the new UI texts that are shown to the user have changed. If you are using text customization, please make sure to update to the identifiers from the tab SDK v5 text section.

• The API showScreenSuccessFaceCapture is no longer available since enrollment no longer considers the successful face capture step.

• The successAnimationEnabled and later showScreenSuccessFlow field has been renamed to showSuccessFeedback.

• The showScreenFailureFlow field has been renamed to showFailureFeedback.

• The showScreenInstructions field has been renamed to showInstructionsScreen.

• The enrollment progress onProgress callback is no longer available since progress is not shown with the updated UX.

4.8.2 iOS - 4.8.3 Android

Highlights

• Improved biometric performance.

• Improved error handling and information - docs .

• SDK Size Reduction.

• Support for iOS emulator.

• Fix (Android): addressed biometric performance on Pixel devices.

• Fix (Android): on premise remove validate device before authenticate

Improved error handling and information

• Introduced a new "Rejected" error - we have split out instances where Liveness could not be established into a new "Rejected" error. Previously these were all labelled as "Spoofing" errors, however we recognized that in some instances these incorrectly added a framed the authentication attempt as more malicious than was fair. Please note, the guidance remains that all modelling is in some way predictive and thefore we would still advise that "Spoofing" does not guarantee that there was malicious intent and for various reasons it's still better to assume positive intent in how you handle these with users.

SDK Size Reduction

Following customer feedback, we have reduced the size of the biometric libraries which has reduced both the iOS and Android SDK integration and download size. Please note that integration size can vary significantly between customers so please contact us if you have questions in this area.

Support for iOS emulator

The Keyless iOS SDK can now be run on an iOS emulator on both Windows PC or Mac, allowing integrators to achieve faster develop and test cycles as they make changes.

4.7.5 iOS - 4.7.6 Android

Highlights

• Fix: fix client state retro compatibility with version >2.0.0 of the Keyless Agent

4.7.4

Highlights

• UX: optional screens - it is now possible to opt-out the optional screens you don’t wish to show - docs

• Enhancement: query remaining lockout time - docs\

UX: optional screens

We understand that the experience our customers create for their end users is of the utmost importance. To provide greater flexibility, we’ve made certain screens and steps in the Authentication and Enrollment flows optional. These screens will remain visible by default, but you now have the ability to opt out of displaying those that are not relevant to your workflow. For more details, please refer to the documentation.

Please note that the camera view and Step 2 (“Enrollment Progress”) will remain mandatory for now, as they are critical to ensuring liveness detection and security during the capture process. However, Step 2 is highly customizable in terms of text and color scheme to align with your branding.

In upcoming releases, we will also be adding sample code and “User Flow” guides to further empower integrators and designers in tailoring their user experience.

Enhancement: query remaining lockout time

Customers can configure the maximum number of errors a user can make before being locked out for a 10-minute period.

Based on customer feedback, we’ve enhanced this feature to allow querying the remaining lockout time (in seconds) after a user has been locked out. For implementation details, please refer to the documentation.

This enhancement enables customers to display the remaining lockout time to users at any given moment, improving transparency and user experience.

Bugs and Fixes

• Fix (Android): Resolved a compatibility issue between the Compose Material library and Flutter.

4.7.3

• UX: SDK Theme is customizable by customer - docs

• Feature: possibility to specify a path to Keyless artifacts. Artifacts are provided by Keyless by default. Artifacts path can be overridden by the customer.

4.7.2

• Feature: improved PSD2 compliance - docs

• Feature: account recovery - docs

• Fix: remove lottie dependency

• UX: remove success animation in favor of static image