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

The Validations SDK uses a two-key system, and you need both keys to integrate:

• Generator Key — A long-lived master key whose only grant is to create SDK keys. It lives on your backend and must never be shipped inside your mobile app.
• SDK Key (temporary) — A short-lived key created from the Generator Key for a single validation session. This is the key type the SDK actually consumes; any other key type will result in an error.

The flow is always the same: create the Generator Key once, then use it to mint a fresh SDK key per validation session.

Step 1 — Create the Generator Key

The Generator Key can only be created via the API, authenticated with an existing backend key. So this is a two-part step you do once:

1. Create a backend key from the dashboard. Follow the authentication guide to generate your API key from the dashboard.
2. Use that backend key to create the Generator Key by calling /v1/api-keys with the backend key in the request header:

• Truora-API-Key: <your backend key>

                
{
    "key_name": "sdk-generator",
    "key_type": "generator",
    "grant": "generator",
    "api_key_version": "1"
}

            

Store the resulting Generator Key securely on your backend — it must never be shipped inside your mobile app.

Step 2 — Use the Generator Key to create an SDK key

For each validation session, call the same /v1/api-keys endpoint authenticated with your Generator Key. Add the following header to the request:

• Truora-API-Key: <your generator key>

Each SDK key is scoped to your application id and a single validation session, and expires automatically.

                
{
    "key_type": "sdk",
    "key_name": "sdk-key",
    "api_key_version": "1",
    "application_id": "APPLICATION_ID",
    "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:

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();

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();

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

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
}

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();

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: