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

# White-Label Walkthrough

> Take an OEM deployment from neutral VisIQ chrome to your own brand and domain — branding, domain verification, preview, and go-live.

This walkthrough takes an OEM partner from a freshly provisioned account to a
fully white-labeled deployment: your name, your logo, your colors, your domain.
Each stage names the Partner Portal screen and the equivalent API call. The
**branding API is live today**; the portal screens and the custom-domain flow
are **rolling out with the Partner Portal** — stages that depend on them are
marked below.

<Note>
  Prerequisites: an active OEM partner account and a **live** provisioning key
  (`vqp_…`). Partner-level branding renders on live end-user surfaces, so
  `PATCH /branding` requires a live key — a test-mode key can read it but a
  test-mode write is rejected (`403 sandbox_read_only`). To rehearse branding
  without touching production, brand a **sandbox sub-tenant** with a test-mode
  key via `PATCH /tenants/{id}/branding` — see the
  [sandbox guide](/partners/oem-sandbox).
</Note>

## 1. Set your branding

**Portal → Settings → Branding** (portal screen rolling out — the API below is
live today). Upload your logos and set your display name, support email, and
palette via the partner-level branding endpoint:

```http theme={null}
PATCH /branding
{
  "displayName": "Acme Guard",
  "logoUrl": "https://cdn.acme.com/logo.png",
  "logoDarkUrl": "https://cdn.acme.com/logo-dark.png",
  "iconUrl": "https://cdn.acme.com/icon.png",
  "supportEmail": "support@acme.com",
  "palette": { "primary": "#7c3aed", "accent": "#a855f7" },
  "fromName": "Acme Security"
}
```

Partner-level branding is the **default** every sub-tenant inherits. To brand a
single sub-tenant differently, set `PATCH /tenants/{id}/branding` — the
per-tenant object wins wherever it is set. Field constraints and the palette
allowlist are documented in the
[OEM Partner API — branding fields](/partners/oem-api#branding-fields).

## 2. Custom domain

<Note>
  **Rolling out with the Partner Portal's Custom Domain screen.** The domain
  lifecycle below describes the flow as it ships; the portal issues the **exact**
  DNS record names and values for your domain when you add it — always copy the
  records from the portal rather than from this page.
</Note>

**Portal → Settings → Custom Domain → Add domain.** Enter the hostname your
end users will see (e.g. `guard.acme.com`). The flow has two DNS steps:

1. **Prove ownership (TXT).** The portal issues an ownership token to publish
   as a `_visiq-verify` **TXT** record on your domain. The domain sits in
   `pending_ownership` until the record is visible.
2. **Point traffic at VisIQ (CNAME).** Once ownership is proven the domain
   moves to `pending_dns`; add the **CNAME** record the portal shows to route
   the hostname to VisIQ's edge.

The platform then checks both records, provisions the TLS certificate, and
walks the domain through `verifying` → `active`. A misconfigured record parks
it at `failed` with the failing check named — fix the record and re-verify.
DNS propagation can take up to an hour depending on your provider's TTLs. One
non-failed/disabled domain per partner at a time.

## 3. Preview and go live

*Ships with the Partner Portal alongside the Custom Domain screen.* With
branding saved (and the domain `active`), the portal's **Branding → Preview**
renders the end-user surfaces (sign-in, HITL approval
prompt, portal chrome) with your branding applied — in both light and dark
modes — before any end user sees them. Review your logo contrast on the dark
surfaces (`logoDarkUrl`) in particular. Flipping the domain to serve traffic
makes it the canonical host for your embedded sub-tenants: existing sessions
are unaffected; new sign-ins land on your domain. Every branding and domain
change is written to your partner audit log (`GET /audit`).

## v1 limitations

Honest edges of white-labeling today — plan your rollout around them:

| Area                   | v1 behavior                                                                                                                                                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Passkeys / WebAuthn    | Passkeys are pinned to the **primary VisIQ domain** (the WebAuthn relying-party ID). End users who registered a passkey before your custom domain went live must re-register it; passkeys do not carry across domains.                  |
| Auth emails            | GoTrue authentication emails (confirmation, magic link, password reset) are sent with **neutral VisIQ styling** — partner branding does not yet apply to them.                                                                          |
| Email sending domain   | All outbound email is sent **from VisIQ's sending domain**. `fromName` customizes the display name only; the from address and DKIM/SPF alignment stay VisIQ's. Partner sending domains (custom from address + DKIM) are on the roadmap. |
| HITL surfaces          | `displayName` branding renders on Slack approval prompts today; Teams and full email template white-labeling are on the roadmap.                                                                                                        |
| One domain per partner | One non-terminal custom domain per partner at a time. Disable the active domain before migrating to a new hostname.                                                                                                                     |
| Palette scope          | Theming is limited to the allowlisted `primary` and `accent` tokens; the neutral scale, typography, and layout are not customizable.                                                                                                    |