In this short guide, you will learn how to integrate the Keyless SDK in your Android or iOS mobile application, and enroll and authenticate users through the Keyless platform.
Before jumping into your code editor, make sure that you're familiar with the various components of the authentication system, and common biometic authentication flows.
Prerequisites
Make sure you have both required API keys, and the list of productions hosts from your Keyless contact:
YOUR_CLOUDSMITH_TOKEN to download the SDK from cloudsmith repository
KEYLESS_API_KEY to configure the mobile SDK
KEYLESS_HOSTS a list of node URLs. Urls in KEYLESS_HOSTS must NOT contain any trailing slashes /.
Set up a physical iOS device for running your app and enable the following permissions:
Enable Camera permissions: add the Privacy - Camera Usage Description key in your project’s Info.plist by adding the following (in XCode under Project > Info):
<key>NSCameraUsageDescription</key><string>Keyless needs access to your camera to enroll and authenticate you. Keyless cannot be used without your camera. Please allow camera permissions.</string>
Enable background processing: necessary to synchronize Keyless data. You can find a comprehensive guide in the apple documentation. In a nutshell here is what you need to do: enable the Background processing mode under Signing & Capabilities/Background Modes. Then, add the following in your project’s Info.plit (in XCode, under the key Permitted background task scheduler identifiers):
Extend any androidX activity that implements the interface for you, for example let your Activity extend the generic ComponentActivity or the more widespread AppCompatActivity.
If you use Proguard, add the following rules to your Proguard configuration file:
# Keyless Proguard
-keep class io.keyless.sdk.** {*;}
-keepclassmembers class io.keyless.sdk.** {*;}
In the the repositories section of the settings.gradle file of your Android application, add the following snippet, replacing YOUR_CLOUDSMITH_TOKEN with the CloudSmith token provided to you by Keyless.
In the android block of your project build.gradle file, typically app/build.gradle, make sure you have the following options:
android {
// ...
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
// add the following only if you're using Kotlin
kotlinOptions {
jvmTarget = "1.8"
}
}
Create a Podfile if you don’t already have one
$ cd your-project-directory
$ pod init
Add the KeylessSDK pod to your Podfile
# This is the Keyless repository for partners
source 'https://dl.cloudsmith.io/YOUR_CLOUDSMITH_TOKEN/keyless/partners/cocoapods/index.git'
target 'MyApp' do
use_frameworks!
# Add the Keyless pod
pod 'KeylessSDK'
end
Add the following at the bottom of your Podfile
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['ENABLE_BITCODE'] = 'NO'
end
end
end
Install the pods.
$ pod install
Analyzing dependencies
Cloning spec repo `cloudsmith-YOUR_CLOUDSMITH_TOKEN-keyless-partners-cocoapods-index` from `https://dl.cloudsmith.io/YOUR_CLOUDSMITH_TOKEN/keyless/partners/cocoapods/index.git`
Where YOUR_CUSTOM_TOKEN should be replaced with the cloudsmith token provided by the Keyless integration support team.
In the example repo you can see that we are using a file to simulate env properties containing the cloudsmith token. You will read the following snippet:
You can read the cloudsmith token from a file cloudsmith.properties that you need to create at the root project directory.
File content shall be the following: cloudsmithToken=YOUR_CUSTOM_TOKEN
Then, open your Android.manifest file and add the following lines inside the <application> tag:
Where YOUR_CUSTOM_TOKEN should be replaced with the cloudsmith token provided by the Keyless integration support team.
In the example repo you can see that we are using a file to simulate env properties containing the cloudsmith token. You will read the following snippet:
File content shall be the following: cloudsmithToken=YOUR_CUSTOM_TOKEN
Then, navigate to your Info.plist file, typically located in a folder called with your project name (e.g. Runner).
Add the following permissions declaration to this file (if not present already):
<key>NSCameraUsageDescription</key>
<string>Keyless needs access to your camera to enroll and authenticate you. Keyless cannot be used without your camera. Please allow camera permissions.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Keyless needs access to your camera to enroll and authenticate you. Keyless cannot be used without your camera. Please allow camera permissions.</string>
1. Configure Access to the Private Registry
Create a .npmrc file in the root of your project. This file will tell your package manager where to find the Keyless SDK and how to authenticate. Add the following lines:
Note: Replace YOUR_CLOUDSMITH_TOKEN with your token.
Verify Kotlin Version: The Keyless SDK requires a minimum Kotlin version of 2.2.0. Depending on your React Native project's configuration, this is specified in one of two files.
If your project uses settings.gradle for plugins (modern setup): Open your android/settings.gradle file and ensure the version for org.jetbrains.kotlin.android is 2.2.0 or higher.
// android/settings.gradle
pluginManagement {
plugins {
// ... other plugins
id "org.jetbrains.kotlin.android" version "2.2.0" apply false // ✅ Must be 2.2.0 or higher
}
}
If your project uses build.gradle for plugins (older setup): Open your root android/build.gradle file. The kotlinVersion variable is defined in the ext block and then used in the dependencies block. Proverite da je verzija 2.2.0 or higher.
// android/build.gradle
buildscript {
ext {
// ... other variables
kotlinVersion = "2.2.0" // ✅ 1. Define version here (must be 2.2.0 or higher)
}
repositories {
google()
mavenCentral()
}
dependencies {
// ... other classpaths
classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion") // ✅ 2. The variable is used on this line
}
}
iOS Setup
Target iOS 13 or Higher: In your ios/Podfile, ensure the platform version is set to 13.0 or higher: platform :ios, '13.0'.
Add the Private Spec Repo: Open your ios/Podfile and add the Keyless Cocoapods source at the top of the file:
# Add the Keyless source at the top
source 'https://dl.cloudsmith.io/YOUR_CLOUDSMITH_TOKEN/keyless/partners-rc/cocoapods/index.git'
source 'https://cdn.cocoapods.org/'
Note: Replace YOUR_CLOUDSMITH_TOKEN with your token.
Enable Camera Permissions: Open your ios/Info.plist file and add the camera usage description.
<key>NSCameraUsageDescription</key>
<string>This app uses the camera to scan face.</string>
Install Native Dependencies: Navigate to the ios directory and run pod install.
cd ios && pod install
Essential configuration
There is some essential configuration to do before you can use the Keyless SDK.
Initialize the Keyless SDK in your Application class:
Configure the Keyless SDK from your MainActivity, ViewModel or any class you use to communicate with Keyless. Note that configure is asynchronous so wait for the completion callback before calling the next Keyless APIs
The configure method requires a SetupConfig as parameter, as well as the KEYLESS_API_KEY and KEYLESS_HOSTS you received from Keyless. You should listen to the result as follows:
val setupConfig = SetupConfig(
apiKey = "KEYLESS_API_KEY",
hosts = listOf("KEYLESS_HOSTS")
)
Keyless.configure(setupConfig) { result ->
when (result) {
is Keyless.KeylessResult.Success -> {
Log.d("KeylessSDK", "configure success")
// Keyless is ready, you can now call
// enroll/authenticate/deEnroll ...
}
is Keyless.KeylessResult.Failure ->{
Log.d("KeylessSDK", "configure error")
// Inspect result.error for more info
}
}
}
Create an instance object of Keyless.SetupConfiguration and pass it to the Keyless.configure method, typically this is done in your app’s application(:didFinishLaunchingWithOptions: method:).
let setupConfig = SetupConfig(
apiKey: "KEYLESS_API_KEY",
hosts: ["KEYLESS_HOSTS"]
)
if let error = Keyless.configure(configuration: setupConfig) {
print("Keyless.Configure failed with error: \(error)")
}
Initialize the Keyless SDK in your Application class:
Configure the Keyless SDK from your MainActivity, ViewModel or any class you use to communicate with Keyless. Note that configure is asynchronous so wait for the completion callback before calling the next Keyless APIs
The configure method requires a SetupConfiguration as parameter, as well as the KEYLESS_API_KEY and KEYLESS_HOSTS you received from Keyless. You should listen to the result as follows:
val setupConfiguration = SetupConfiguration.builder
.withApiKey("KEYLESS_API_KEY")
.withHosts(listOf("KEYLESS_HOSTS"))
.build()
Keyless.configure(setupConfiguration) { result ->
when (result) {
is Keyless.KeylessResult.Success -> {
Log.d("KeylessSDK", "configure success")
// Keyless is ready, you can now call
// enroll/authenticate/deEnroll ...
}
is Keyless.KeylessResult.Failure ->{
Log.d("KeylessSDK", "configure error")
// Inspect result.error for more info
}
}
}
Create an instance object of Keyless.SetupConfiguration and pass it to the Keyless.configure method, typically this is done in your app’s application(:didFinishLaunchingWithOptions: method:).
let setupConfiguration = Keyless.SetupConfiguration.builder
.withApiKey("KEYLESS_API_KEY")
.withHosts(["KEYLESS_HOSTS"])
.build()
if let error = Keyless.configure(configuration: setupConfiguration) {
print("Keyless.Configure failed with error: \(error)")
}
Configure the Keyless SDK in your app's initialization code:
final setupConfiguration = SetupConfiguration(
apiKey: "KEYLESS_API_KEY",
hosts: ["KEYLESS_HOSTS"],
);
try {
await Keyless.instance.configure(setupConfiguration);
print("Keyless SDK configured successfully");
// Keyless is ready, you can now call
// enroll/authenticate/deEnroll ...
} catch (error) {
print("Failed to configure Keyless SDK: $error");
// Handle error
}
Make sure to set up the required permissions in both Android and iOS platforms as described in their respective tabs.
Initialize the Native SDK for Android: Open your MainApplication.kt (or .java) file and add the call to KeylessSDKModule.initialize() inside the onCreate method.
// In MainApplication.kt
import io.reactnative.keyless.sdk.KeylessSDKModule // <-- Add this import
override fun onCreate() {
super.onCreate()
// Initialize Keyless
KeylessSDKModule.initialize(application = this)
// ... rest of your onCreate method
}
Configure the Keyless SDK: This is best done once when your application starts, after the native SDK has been initialized.
Call the configure method with your credentials. The method returns a result object that you can handle using the fold method.
import Keyless, { SetupConfig } from '@react-native-keyless/sdk';
const config = new SetupConfig({
// Make sure to store your keys securely
apiKey: 'KEYLESS_API_KEY',
hosts: ['KEYLESS_HOSTS'],
});
const result = await Keyless.configure(config);
result.fold({
onSuccess: data => {
console.log('Keyless SDK configured successfully:', data);
// Keyless is ready, you can now call other methods
},
onFailure: error => {
console.error('Failed to configure Keyless SDK:', error);
},
});
Additional configuration
As well as the essential configuration parameters, you can also specify the optional configuration parameters detailed in the following sections. You can inspect the Config class to see optional parameters (or the builder to see exposed methods)
Logging
Logging is disabled by default.
Please note logs do not include any Personally Identifiable Information (PII).
Keyless allows you to:
enable logging to the Keyless infrastructure - keylessLogsConfiguration
collect logging for you own analytics without sending them to the Keyless infrastructure - customLogsConfiguration
Collect logs after setting up custom logging with customLogsConfiguration option:
Start collecting the Keyless.customLogs flow (This must happen before a Keyless.configure() to get all Logs Events):
Keyless.customLogs.collect { logEvent ->
// handle the logEvent
}
Configure the SDK with the following SetupConfig:
val setup = SetupConfig(
apiKey = "...",
hosts = listOf(""),
customLogsConfiguration = LogsConfiguration(
enabled = true,
logLevel = LogLevels.INFO // This is optional and defaults to INFO
)
)
var myEventCollection = [LogEvent]()
let configuration = Keyless.SetupConfiguration
.builder
.withApiKey("some api key")
.withHosts(["some.host"])
.withLogging(
keylessLogsConfiguration: KeylessLogsConfiguration(enabled: true, logLevel: .INFO),
customLogsConfiguration: CustomLogsConfiguration(enabled: true, callback: { event in
myEventCollection.append(event)
})
)
.build()
Keyless.configure(setupConfiguration: configuration) { error in
// handle error
}
}
Start collecting Keyless suctom logs flow (This must happen before a Keyless.configure() to get all Logs Events)
When you want to unsubscribe from logs make sure you call:
eventSubscription?.unsubscribe();
Logging Levels
You may set different logging levels to provide more or less information in logs.
The available levels are the following:
INFO (default)
DEBUG
TRACE
The TRACE level provides the following additional data:
userId
devicePublicSigningKey
coreLogHistory (used for detailed debugging)
Liveness Lockout policy
Since version 5.0.0 of the SDK the lockout policy is no longer processed on the client for security reasons.
The lockout policy is applied only during authentication and can be confiured server side.
Keyless has both client side (applicable to a specific device) and server side (applicable to all users and devices) lockout policies to help prevent brute force attacks.
Client side lockout is configurable in the SDK, and determines how many failed login attempts (lockoutAttemptsThreshold) are allowed over a set time period (lockoutAttemptsResetAfter) before the user is locked out for the set duration (lockoutDuration) on that device.
Account lockoutDuration must be greater than or equal to the lockoutAttemptsResetAfter so that it is not reset by lockoutAttemptsResetAfter.
Server side lockout works similarly, except applies to all authentication devices for a specific user, and is configured to lock a user out for 10 minutes after 5 failed attempts. A successful login resets the count of failed authentication attempts to zero.
Tampered device check
Keyless provides a tampered device check that can be enabled within the Mobile SDK configurations. This service looks for signs of rooting, or jailbreaking, whereby a smartphone or tablet may have been tampered with in order to gain greater administrative control over it, a tactic used by malicious actors.
You can enable the check by:
Calling the withTamperedDeviceCheck() on the SetupConfigurationBuilder if using the legacy SetupConfiguration.
Setting withDevicePrivileges to true if using the new SetupConfig.
If you enable this check, and the SDK detects that the phone was tampered with, the Keyless SDK will return an error and prevent the user from authenticating.
As ever, we advise clients that no security measure is perfect and we can't guarantee 100% detection success rate. Therefore we recommend taking advice or carry out further research on how else to harden the security of your own app if this is a particular concern.
Enrollment circuits
To speed up enrollment you can use the numberOfEnrollmentCircuits to upload less than the default of five circuits upon enrollment. The remainder (50 - numberOfEnrollmentCircuits) are uploaded asynchronously.
Shared circuits
This is the target desired number of circuits kept on the server. To set this number use the numberOfSharedCircuits.
Networking module
If you need to perform network requests on behalf of Keyless SDK, you can implement the KLNetworkingModule interface. Set the networkingModule parameter with an instance of the KLNetworkingModule:
public interface KLNetworkingModule {
public fun sendHTTPRequest(
baseUrl: String,
path: String,
method: String,
headers: Map<String, String>,
body: String
): KLHTTPResponse
public data class KLHTTPResponse(
val errorCode: Int,
val httpCode: Int,
val responseBody: String
)
}
public protocol KLNetworkingModule {
func sendHTTPRequest (
host: String,
url : String,
method: String,
headers : [String: String],
body : String) -> KLHTTPResponse
}
public struct KLHTTPResponse {
var errorCode: Int
var httpCode: Int
var responseBody : String
public init(errorCode: Int, httpCode: Int, responseBody: String) {
self.errorCode = errorCode
self.httpCode = httpCode
self.responseBody = responseBody
}
}