Getting started: Shared logic

This guide contains the shared logic used across all Truora Validations SDK integrations (Android, iOS, Flutter, React Native).

Prerequisites & Authentication

API Keys

Truora uses a Generator Key system.

• Generator Key: A master API key with grants to only generate other SDK API keys. Your backend uses this key to generate temporary SDK keys on demand.

                
curl --location 'https://api.account.truora.com/v1/api-keys' \
--header 'Truora-API-Key: API KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'key_name=sdk-generator' \
--data-urlencode 'key_type=generator' \
--data-urlencode 'grant=generator' \
--data-urlencode 'api_key_version=1'

            

• Temporary Keys (sdk keys): Short-lived keys generated using the Generator Key. Each SDK key is scoped to your application id and a single validation session. It also expires automatically.

                
curl --location 'https://api.account.truora.com/v1/api-keys' \
  --header 'Truora-API-Key: GENERATOR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'key_type=sdk' \
  --data-urlencode 'key_name=sdk-key' \
  --data-urlencode 'api_key_version=1' \
  --data-urlencode 'application_id=APPLICATION_ID' \
  --data-urlencode 'account_id=ACCOUNT_ID'

            

Request parameters

application_id — Your app’s bundle identifier (e.g., com.yourcompany.yourapp on iOS, com.yourcompany.yourapp on Android). This value is embedded in the generated SDK key and the SDK validates it against the running app’s actual bundle ID at runtime. If they don’t match, the key is rejected. You can find your application ID in:

• iOS: Bundle.main.bundleIdentifier — set in Xcode under your target’s General > Bundle Identifier.
• Android: The applicationId in your app-level build.gradle file.
• Flutter: The applicationId (Android) and PRODUCT_BUNDLE_IDENTIFIER (iOS) in the platform-specific project files.
• React Native: Same as the native iOS/Android values above.

account_id — A unique identifier for the end user on your platform (e.g., an internal user ID, UUID, or database primary key). This value ties the SDK key to a specific user session. If the same user needs to perform another validation, use the same account_id. Constraints:

• Maximum 200 characters.
• Allowed characters: alphanumeric (a-z, A-Z, 0-9), ., _, -, !, *.

Important: The account_id must be assigned by your backend — never use a value provided by the end user (such as an email or phone number). Using user-controlled input as the account identifier can lead to security vulnerabilities and UX issues like session collisions between users.

How to provide the API Key to the SDK

There are two options for supplying the SDK key to your mobile application:

1. Retrieve from a backend (Recommended): Your backend generates SDK keys on demand using the Generator Key, and sends them to the mobile app. This is the most secure approach since the Generator Key never leaves your server.
2. Encrypted storage: Store a pre-generated SDK key in the device’s encrypted storage (e.g., Keychain on iOS, EncryptedSharedPreferences on Android). The key must be retrieved and cached synchronously, or fetched asynchronously before SDK initialization is called.

Backend integration (Recommended)

When using the recommended backend approach, the communication flow is:

1. The mobile app requests an SDK key from your backend
2. Your backend calls the Truora API using the Generator Key
3. Truora returns a temporary SDK key
4. Your backend forwards the SDK key to the mobile app
5. The mobile app initializes the Truora SDK with this temporary key

Note: Platform-specific examples for each option are available in each platform’s dedicated documentation.

UI Customization

Customize the validation UI to match your brand:

React Native (TypeScript)

                
const uiConfig: UIConfig = {
  primaryColor: '#435AE0',
  onPrimaryColor: '#FFFFFF',
  secondaryColor: '#03DAC6',
  surfaceColor: '#FFFFFF',
  onSurfaceColor: '#000000',
  errorColor: '#FF5454',
  logoUrl: 'https://your-cdn.com/logo.png',
};

await TruoraSDK.initialize({
  getApiKeyFromSecureStorage: () => getApiKey(),
  userId: 'user-123',
  ui: uiConfig,
  validation: {
    type: 'face',
    useAutocapture: true,
    waitForResults: true,
    timeout: 120,
  },
});

const result = await TruoraSDK.start();

            

Flutter (Dart)

                
final uiConfig = UIConfig(
  primaryColor: '#435AE0',
  onPrimaryColor: '#FFFFFF',
  secondaryColor: '#03DAC6',
  surfaceColor: '#FFFFFF',
  onSurfaceColor: '#000000',
  errorColor: '#FF5454',
  logoUrl: 'https://your-cdn.com/logo.png',
);

await TruoraValidationsSDK.initialize(InitializeConfig(
  getApiKeyFromSecureStorage: () => getApiKey(),
  userId: 'user-123',
  uiConfig: uiConfig,
  validation: FaceConfig(FaceValidationConfig(
    useAutocapture: true,
    waitForResults: true,
    timeout: 120,
  )),
));

final result = await TruoraValidationsSDK.start();

            

iOS (Swift)

                
let validation = TruoraValidationsSDK.Builder(
    apiKeyGenerator: self,
    userId: "user-123"
)
.withConfig { config in
    config
        .setPrimaryColor("#435AE0")
        .setOnPrimaryColor("#FFFFFF")
        .setSecondaryColor("#03DAC6")
        .setSurfaceColor("#FFFFFF")
        .setOnSurfaceColor("#000000")
        .setErrorColor("#FF5454")
        .setLogo("https://your-cdn.com/logo.png")
}
.withValidation { (face: Face) in
    face.withAutocapture(true)
}
.build()

await validation.start(from: viewController) { result in
    // handle result
}


            

Android (Kotlin)

                
TruoraSDK.Validations.Builder(this, "user-123")
    .withUIConfig { uiBuilder ->
        uiBuilder
            .withPrimaryColor("#435AE0")
            .withOnPrimaryColor("#FFFFFF")
            .withSecondaryColor("#03DAC6")
            .withSurfaceColor("#FFFFFF")
            .withOnSurfaceColor("#000000")
            .withErrorColor("#FF5454")
            .withLogoUrl("https://your-cdn.com/logo.png")
            .build()
    }
    .withValidation { faceBuilder ->
        faceBuilder
            .withAutocapture(true)
            .build()
    }
    .build(validationHandler)

validationHandler.start()

            

Android (Java)

                
TruoraSDK.Validations.Builder(this, "user-123")
    .withUIConfig(uiBuilder ->
        uiBuilder
            .withPrimaryColor("#435AE0")
            .withOnPrimaryColor("#FFFFFF")
            .withSecondaryColor("#03DAC6")
            .withSurfaceColor("#FFFFFF")
            .withOnSurfaceColor("#000000")
            .withErrorColor("#FF5454")
            .withLogoUrl("https://your-cdn.com/logo.png")
            .build()
    )
    .withValidation(faceBuilder ->
        faceBuilder
            .withAutocapture(true)
            .build()
    )
    .build(validationHandler);

validationHandler.start();

            

UI Configuration Parameters:

Default theme color showcase

Using the default Truora colors this is how some of our screens would look like:

Custom theme color showcase

Following a custom theme with the “Google” logo and the colorset:

                
{
  "primaryColor": "#8B0000",
  "onPrimaryColor": "#FFFFFF",
  "secondaryColor": "#2F4F4F",
  "onSecondaryColor": "#E0E0E0",
  "surfaceColor": "#151419",
  "onSurfaceColor": "#D9CEC1",
  "surfaceVariantColor": "#252329",
  "onSurfaceVariantColor": "#A39B8F",
  "errorColor": "#CF6679"
}

            

We would get the following color customization: