> ## Documentation Index
> Fetch the complete documentation index at: https://docs.facesign.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Customization

> Customize the FaceSign verification permissions page and UI controls for a branded user experience.

Customize the FaceSign verification permissions page and UI controls to match your brand and user experience requirements.

## Overview

FaceSign provides customization options for the permissions page shown before verification begins and global UI control settings. Customizations are applied when creating a session.

<Note>
  Customizations are optional. If not provided, FaceSign uses sensible defaults with your configured avatar.
</Note>

***

## Permissions Page

The `permissionsPage` property customizes the page that asks for camera/microphone permissions. Use it to change text, background, and translations.

### Available Options

| Property                | Type                     | Description                                                                              |
| ----------------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
| `buttonText`            | `string`                 | Text displayed on the start button (e.g., "Begin Verification"). Defaults to "Continue". |
| `mainHeading`           | `string`                 | Primary heading text shown at the top of the permissions page.                           |
| `subheading`            | `string`                 | Secondary text providing additional context below the main heading.                      |
| `backgroundType`        | `"AVATAR" \| "COLOR"`    | Page background: `"AVATAR"` (default, shows avatar image) or `"COLOR"` (solid color).    |
| `backgroundColor`       | `string`                 | Background color when `backgroundType` is `"COLOR"` (e.g., `"#f0f0f0"`).                 |
| `buttonTextTranslates`  | `Record<string, string>` | Button text translations by language code (e.g., `"es"`, `"fr"`).                        |
| `mainHeadingTranslates` | `Record<string, string>` | Main heading translations by language.                                                   |
| `subheadingTranslates`  | `Record<string, string>` | Subheading translations by language.                                                     |

```json title="Permissions Page Customization" wrap theme={null}
{
  "permissionsPage": {
    "mainHeading": "Identity Verification",
    "subheading": "We need camera access to verify your identity",
    "buttonText": "Start Verification",
    "backgroundType": "COLOR",
    "backgroundColor": "#1a202c"
  }
}
```

***

## UI Controls

Global UI control settings that apply throughout the verification session.

### Available Options

| Property         | Type      | Description                                                               |
| ---------------- | --------- | ------------------------------------------------------------------------- |
| `showUxControls` | `boolean` | Show or hide UX control elements during verification. Defaults to `true`. |

```json title="UI Controls Customization" wrap theme={null}
{
  "controls": { "showUxControls": false }
}
```

***

## Multi-language Support

Use *Translates fields* to provide translated text for multi-language sessions. Language keys should match ISO codes.

### Translation Fields

| Property                | Type                     | Description                           |
| ----------------------- | ------------------------ | ------------------------------------- |
| `buttonTextTranslates`  | `Record<string, string>` | Button translations by language code. |
| `mainHeadingTranslates` | `Record<string, string>` | Main heading translations.            |
| `subheadingTranslates`  | `Record<string, string>` | Subheading translations.              |

<Note>
  Multi-language sessions also require `langs` and `defaultLang` fields at the session level.
</Note>

```json title="Multi-language Example" wrap theme={null}
{
  "permissionsPage": {
    "mainHeading": "Identity Verification",
    "mainHeadingTranslates": { "es": "Verificación de Identidad", "fr": "Vérification d'identité" },
    "subheading": "Camera access required",
    "subheadingTranslates": { "es": "Se requiere acceso a la cámara", "fr": "Accès à la caméra requis" },
    "buttonText": "Continue",
    "buttonTextTranslates": { "es": "Continuar", "fr": "Continuer" }
  }
}
```

***

## Implementation

Supply a `customization` object when creating a session. Nested fields are optional -- only include what's needed.

### Complete Example

This example shows all customization options combined: custom permissions page with color background, multi-language support for English/Spanish/French, and hidden UX controls for a minimal interface.

<Tabs>
  <Tab title="cURL">
    ```bash wrap theme={null}
    curl https://api.facesign.ai/sessions \
      -H "Authorization: Bearer sk_test_..." \
      -H "Content-Type: application/json" \
      -d '{
        "clientReferenceId": "user-123",
        "langs": ["en", "es", "fr"],
        "defaultLang": "en",
        "metadata": {},
        "flow": [
          { "id": "start", "type": "start", "outcome": "end" },
          { "id": "end", "type": "end" }
        ],
        "customization": {
          "permissionsPage": {
            "mainHeading": "Verify Your Identity",
            "mainHeadingTranslates": {
              "es": "Verifica tu Identidad",
              "fr": "Vérifiez votre Identité"
            },
            "subheading": "This helps us keep your account secure",
            "subheadingTranslates": {
              "es": "Esto ayuda a mantener segura tu cuenta",
              "fr": "Cela aide à sécuriser votre compte"
            },
            "buttonText": "Begin Verification",
            "buttonTextTranslates": {
              "es": "Comenzar Verificación",
              "fr": "Commencer la Vérification"
            },
            "backgroundType": "COLOR",
            "backgroundColor": "#1a202c"
          },
          "controls": {
            "showUxControls": false
          }
        }
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript wrap theme={null}
    const client = new Client({
      auth: 'sk_test_...',
    })

    const { session, clientSecret } = await client.session.create({
      clientReferenceId: "user-123",
      langs: ["en", "es", "fr"],
      defaultLang: "en",
      metadata: {},
      flow: [
        { id: "start", type: "start", outcome: "end" },
        { id: "end", type: "end" }
      ],
      customization: {
        permissionsPage: {
          mainHeading: "Verify Your Identity",
          mainHeadingTranslates: {
            es: "Verifica tu Identidad",
            fr: "Vérifiez votre Identité"
          },
          subheading: "This helps us keep your account secure",
          subheadingTranslates: {
            es: "Esto ayuda a mantener segura tu cuenta",
            fr: "Cela aide à sécuriser votre compte"
          },
          buttonText: "Begin Verification",
          buttonTextTranslates: {
            es: "Comenzar Verificación",
            fr: "Commencer la Vérification"
          },
          backgroundType: "COLOR",
          backgroundColor: "#1a202c"
        },
        controls: {
          showUxControls: false
        }
      }
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python wrap theme={null}
    import facesignai

    client = facesignai.Client(
        auth='sk_test_...',
    )

    response = client.session.create(
        client_reference_id="user-123",
        langs=["en", "es", "fr"],
        default_lang="en",
        metadata={},
        flow=[
            {"id": "start", "type": "start", "outcome": "end"},
            {"id": "end", "type": "end"}
        ],
        customization={
            "permissionsPage": {
                "mainHeading": "Verify Your Identity",
                "mainHeadingTranslates": {
                    "es": "Verifica tu Identidad",
                    "fr": "Vérifiez votre Identité"
                },
                "subheading": "This helps us keep your account secure",
                "subheadingTranslates": {
                    "es": "Esto ayuda a mantener segura tu cuenta",
                    "fr": "Cela aide à sécuriser votre compte"
                },
                "buttonText": "Begin Verification",
                "buttonTextTranslates": {
                    "es": "Comenzar Verificación",
                    "fr": "Commencer la Vérification"
                },
                "backgroundType": "COLOR",
                "backgroundColor": "#1a202c"
            },
            "controls": {
                "showUxControls": False
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Common Examples

### Minimal Branding

Customize just the heading and button text:

```json title="Minimal Setup" wrap theme={null}
{
    "customization": {
      "permissionsPage": {
        "mainHeading": "Welcome to SecureBank",
        "buttonText": "Get Started"
      }
    }
}
```

### Avatar Background

Default (avatar video):

```json title="Avatar Background" wrap theme={null}
{
    "avatarId": "65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0",
    "customization": {
      "permissionsPage": {
        "backgroundType": "AVATAR",
        "mainHeading": "Let's verify your identity",
        "buttonText": "Start"
      }
    }
}
```

### Color Background

Solid color (with heading and subheading):

```json title="Color Background" wrap theme={null}
{
    "customization": {
      "permissionsPage": {
        "backgroundType": "COLOR",
        "backgroundColor": "#0f172a",
        "mainHeading": "Identity Verification Required",
        "subheading": "We'll guide you through the process",
        "buttonText": "Continue"
      }
    }
}
```

### Multi-language

Switchable "en"/"es":

```json title="Bilingual Setup" wrap theme={null}
{
    "langs": ["en", "es"],
    "defaultLang": "en",
    "customization": {
      "permissionsPage": {
        "mainHeading": "Verification",
        "mainHeadingTranslates": { "es": "Verificación" },
        "buttonText": "Start",
        "buttonTextTranslates": { "es": "Comenzar" }
      }
    }
}
```

<Note>
  Test your customizations across different devices and screen sizes to ensure a consistent user experience.
</Note>

***

## Auto-brand from your website (FaceSign MCP)

The `customization` fields above cover the FaceSign-hosted permissions page. If you want the same brand applied to the **landing** and **recap** pages that wrap the session in your own app — typically generated through the [FaceSign MCP server](/docs/mcp) with `launch_session_ui` or `export_app` — you can point the AI agent at your product website and have it pull the visual language automatically.

Hand the agent a reference URL and ask for a branded demo, for example:

> "Use `https://acme.example.com` as the style reference."

The agent fetches the page with its own web-fetch tool, reads the HTML and CSS, and adopts:

* **Primary accent color** — scanned from CSS custom properties (`--primary`, `--brand`, `--accent`) and the most frequent hex on buttons and links.
* **Typography** — the first two `font-family` declarations on `body` and headings.
* **Border-radius scale** — taken from buttons and cards.
* **Shadow style** — subtle vs. strong drop-shadow feel.
* **Logo** — the first `<img>` inside `<header>` (or with `alt` matching the brand name).

The reference URL is used as **style inspiration only** — the agent won't clone layout, body copy, or images from it.

<Warning>
  **When fetching fails** -- If the reference site is behind auth, Cloudflare, or is a JS-rendered SPA that the web-fetch tool can't introspect, the agent should tell you and ask for explicit hex codes and a font stack rather than silently falling back to a generic default.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Sessions" href="/docs/reference/concepts#sessions">
    Create sessions with customization
  </Card>

  <Card title="Languages" href="/docs/reference/languages">
    Multi-language support
  </Card>

  <Card title="Avatars" href="/docs/reference/avatars">
    Choose AI avatars
  </Card>
</CardGroup>