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

# Custom branding

> Customize your verification pages, emails, and proof bundles with your organization's branding.

Enterprise tenants can apply custom branding to verification pages, transactional emails, and proof bundles. Upload your logo, set brand colors, and preview changes before saving.

<Info>
  Custom branding requires a Business or Enterprise plan, or the White-Label
  add-on. See [billing](/billing/overview) for plan details.
</Info>

## Branding settings

Navigate to **Settings > Branding** in the console to configure your brand.

### Logo

Upload your organization's logo. The logo appears on verification pages, transactional emails, and credential cards.

| Requirement   | Value                |
| :------------ | :------------------- |
| Formats       | PNG, JPEG, SVG, WebP |
| Max file size | 2 MB                 |

### Brand name

Set the name displayed on verification pages and credential cards. This is typically your organization or product name.

### Colors

Configure two colors that define your brand appearance:

| Color       | Where it appears                   | Default   |
| :---------- | :--------------------------------- | :-------- |
| **Primary** | Card headers, primary UI elements  | `#06b6d4` |
| **Accent**  | Badges, tags, secondary highlights | `#0891b2` |

Use the color picker or enter a hex value directly (e.g., `#1a2b3c`).

## Live preview

The branding page includes a live preview panel that shows how your logo, brand name, and colors appear on a credential card. Changes update in real time as you adjust settings.

## Configuring branding

<Steps>
  <Step title="Upload your logo">
    Click the upload area or drag and drop your logo file. The preview updates
    immediately.
  </Step>

  <Step title="Set your brand name">
    Enter your organization name in the Brand Name field.
  </Step>

  <Step title="Choose your colors">
    Use the color pickers to set your primary and accent colors, or enter hex
    values directly.
  </Step>

  <Step title="Save">
    Click **Save Branding** to apply your changes. A confirmation banner
    appears when the save completes.
  </Step>
</Steps>

## Managing branding via the API

You can read and update branding settings programmatically. All write endpoints require the White-Label entitlement.

### Get current branding

```http Request theme={null}
GET /v1/settings/branding
X-API-Key: tl_live_...
```

```json Response theme={null}
{
  "tenant_id": "tn_abc123",
  "brand_name": "Acme Corp",
  "logo_url": "https://cdn.truthlocks.com/branding/tn_abc123/logo/logo.png",
  "primary_color": "#10b981",
  "accent_color": "#059669"
}
```

If no branding has been configured, the response returns the default colors (`#06b6d4` primary, `#0891b2` accent) and no logo.

### Update branding

Set your brand name and colors in a single request:

```http Request theme={null}
PUT /v1/settings/branding
X-API-Key: tl_live_...
Content-Type: application/json

{
  "brand_name": "Acme Corp",
  "primary_color": "#10b981",
  "accent_color": "#059669"
}
```

Colors must be valid hex values in `#RRGGBB` format. Omitted fields keep their current values.

### Upload a logo

Logo uploads use a three-step presigned URL flow:

<Steps>
  <Step title="Request a presigned upload URL">
    ```http Request theme={null}
    POST /v1/settings/branding/logo/presign
    X-API-Key: tl_live_...
    Content-Type: application/json

    {
      "filename": "logo.png",
      "content_type": "image/png",
      "size_bytes": 48000
    }
    ```

    ```json Response theme={null}
    {
      "upload_url": "https://s3.amazonaws.com/...",
      "s3_key": "branding/tn_abc123/logo/ast_xyz/logo.png",
      "asset_id": "ast_xyz",
      "expires_in": 600
    }
    ```

    The presigned URL expires after 10 minutes.
  </Step>

  <Step title="Upload the file to the presigned URL">
    Upload your logo directly to the returned `upload_url` using an HTTP PUT request with the file contents as the body.
  </Step>

  <Step title="Confirm the upload">
    ```http Request theme={null}
    POST /v1/settings/branding/logo/confirm
    X-API-Key: tl_live_...
    Content-Type: application/json

    {
      "asset_id": "ast_xyz",
      "s3_key": "branding/tn_abc123/logo/ast_xyz/logo.png"
    }
    ```

    After confirmation, the new logo appears on all branding surfaces.
  </Step>
</Steps>

<Warning>
  Write endpoints (`PUT /v1/settings/branding`, logo presign, and logo confirm) return HTTP 402 if your plan does not include the White-Label entitlement. See [billing](/billing/overview) for plan details.
</Warning>

## Where branding appears

Your custom branding is applied across several surfaces:

<CardGroup cols={2}>
  <Card title="Verification pages" icon="globe">
    Public proof pages display your logo and brand colors.
  </Card>

  <Card title="Transactional emails" icon="envelope">
    Emails sent on your behalf (e.g., credential deliveries, team invites)
    include your logo.
  </Card>

  <Card title="Proof bundles" icon="file-code">
    Downloaded proof bundles reference your brand name and issuer identity.
  </Card>

  <Card title="Credential cards" icon="id-card">
    The credential card shown to recipients uses your primary color and logo.
  </Card>
</CardGroup>

## Permissions

Updating branding settings requires the `branding.write` permission, which is granted to the **Tenant Admin** and **Org Admin** roles by default. Any authenticated user with `settings.read` can view branding settings.

## Related

<CardGroup cols={2}>
  <Card title="Billing" icon="credit-card" href="/billing/overview">
    Plan tiers and the White-Label add-on.
  </Card>

  <Card title="B2B2C delivery" icon="paper-plane" href="/guides/b2b2c">
    How branded credentials are delivered to consumers.
  </Card>

  <Card title="Custom domains" icon="globe" href="/guides/custom-domains">
    Serve the verification portal and console from your own domain.
  </Card>
</CardGroup>