# Getting started: Shared logic
{{<tags>}}

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](/guides/authentication/) 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>``

{{<code lang="json" method="POST" endpoint="/v1/api-keys" response="Request">}}
{
    "key_name": "sdk-generator",
    "key_type": "generator",
    "grant": "generator",
    "api_key_version": "1"
}
{{</code>}}

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.

{{<code lang="json" method="POST" endpoint="/v1/api-keys" response="Request">}}
{
    "key_type": "sdk",
    "key_name": "sdk-key",
    "api_key_version": "1",
    "application_id": "APPLICATION_ID",
    "account_id": "ACCOUNT_ID"
}
{{</code>}}

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

![Backend integration flow sequence diagram][image1]

***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:

{{<code2 "{\"typescript\": \"sdk_shared_ui_config_typescript.ts\", \"dart\": \"sdk_shared_ui_config_dart.dart\", \"swift\": \"sdk_shared_ui_config_swift.swift\", \"kotlin\": \"sdk_shared_ui_config_kotlin.kt\", \"java\": \"sdk_shared_ui_config_java.java\"}" "UI Customization" >}}

## UI Configuration Parameters:

{{<table "table w-auto small m-auto text-center table-striped table-bordered">}}
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| **primaryColor** | String | Truora blue | Primary brand color |
| **onPrimaryColor** | String | White | Text/icons color on primary elements |
| **secondaryColor** | String | Black | Secondary accent color |
| **onSecondaryColor** | String | White | Text/icons color on secondary elements |
| **surfaceColor** | String | White | Background color |
| **onSurfaceColor** | String | Black | Text/icons color on surface elements |
| **surfaceVariantColor** | String | Truora teal | Secondary background color |
| **onSurfaceVariantColor** | String | White | Text/icons color on surface variant elements |
| **errorColor** | String | Red | Error state color |
| **logoUrl** | String | Truora logo | URL to remote logo image |
{{</table>}}

## Default theme color showcase

Using the default Truora colors this is how some of our screens would look like:   
![Default theme example - Face validation screen][image2]  
![Default theme example - Document validation screen][image3]  
![Default theme example - Results screen][image4]

## Custom theme color showcase

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

{{<code lang="json" lang_title="JSON">}}
{
  "primaryColor": "#8B0000",
  "onPrimaryColor": "#FFFFFF",
  "secondaryColor": "#2F4F4F",
  "onSecondaryColor": "#E0E0E0",
  "surfaceColor": "#151419",
  "onSurfaceColor": "#D9CEC1",
  "surfaceVariantColor": "#252329",
  "onSurfaceVariantColor": "#A39B8F",
  "errorColor": "#CF6679"
}
{{</code>}}

We would get the following color customization:  
![Custom theme example - Face validation screen][image5]

![Custom theme example - Document validation screen][image6]  
![Custom theme example - Results screen][image7]

[image1]: /images/illustrations/validations_sdk/shared_logic_sequence_diagram.png
[image2]: /images/illustrations/validations_sdk/shared_logic_ui_example_0.png
[image3]: /images/illustrations/validations_sdk/shared_logic_ui_example_1.png
[image4]: /images/illustrations/validations_sdk/shared_logic_ui_example_2.png
[image5]: /images/illustrations/validations_sdk/shared_logic_ui_example_3.png
[image6]: /images/illustrations/validations_sdk/shared_logic_ui_example_4.png
[image7]: /images/illustrations/validations_sdk/shared_logic_ui_example_5.png