White-label preview

Embed ClearPDF tools inside partner experiences.

The current artifact is a backend-contract-backed widget preview with theming, domain allowlist checks, privacy copy, and demo code. Live partner deployments remain blocked until account provisioning, domain verification, and contractual controls are retained as evidence.

View widget JS API playground

Widget contract

Contract path /v1/billing/productization/contracts; live partner traffic is blocked until partner approval evidence is retained.

Domain enforcement

Domain allowlists are required, and server-side origin enforcement is required.

Template eligibility

The backend exposes white_label templates only when template.productization.whiteLabelEligible must be true; attribution remains visible by default.

Backend enforcement

server-issued sha256-hashed wlp_ partner bearer token; plaintext returned once; HTTPS-only exact normalized Origin match against partner allowedOrigins plus verified domain state; partner-token jobs are created under the registered partner tenant. Live partner traffic remains blocked.

Token issuance

server-issued sha256-hashed wlw_ widget token accepted by authorization, template, and job enforcement paths for verified origins; plaintext returned once

Domain verification

allowed origins must be verified before authorization, template access, or job creation

Metering and audit

partner-token jobs record partner id, verified origin, attribution requirement, partner billing tenant, per-partner rate-limit state, and partner_widget metering source; registration, domain verification, authorization success, and authorization failure emit hash-only audit events.

Demo behavior

The embeddable script renders a compact launcher, validates the current hostname against configured domains, applies CSS tokens, and links into the selected ClearPDF tool. Upload execution is intentionally delegated to the hosted app or partner backend until live partner controls are enabled.

Eligible template contracts

The list below is read from the templates API with the white-label usage filter. Each row keeps the backend license and productization booleans visible so the page cannot silently market ineligible templates.

Template list unavailable

Templates API /v1/templates?usage=white_label&limit=3 failed

Embed code

Partners can configure the target mount point, default tool, allowed domains, brand name, privacy URL, and visual tokens with script data attributes.

<div id="clearpdf-widget"></div>
<script
  src="https://app.clearpdf.net/embed/clearpdf-widget.js"
  data-target="#clearpdf-widget"
  data-api-origin="https://api.clearpdf.net"
  data-tool="compress-pdf"
  data-job-type="compress_pdf"
  data-partner-id="acme_docs"
  data-widget-token="wlw_browser_scoped_token_from_partner_provisioning"
  data-allowed-domains="docs.acme.com,app.acme.com"
  data-primary-color="#126a6f"
  data-accent-color="#b33c2f"
  data-border-radius="8px"
  data-brand-name="Acme PDF Tools"
  data-privacy-url="https://docs.acme.com/privacy">
</script>

{
  "partnerId": "acme-docs",
  "environment": "sandbox",
  "allowedDomains": ["docs.acme.com", "app.acme.com"],
  "defaultTool": "compress-pdf",
  "theme": {
    "brandName": "Acme PDF Tools",
    "primaryColor": "#126a6f",
    "accentColor": "#b33c2f",
    "surfaceColor": "#ffffff",
    "inkColor": "#172026",
    "borderRadius": "8px"
  },
  "privacy": {
    "mode": "local_first",
    "showClearPdfAttribution": true,
    "partnerPrivacyUrl": "https://docs.acme.com/privacy"
  }
}

Configuration file

Production account setup should store the same values server-side. Client attributes are a rendering hint, not a security boundary.

Theming tokens

Supported tokens are brand name, primary color, accent color, surface color, ink color, border radius, and attribution display.

Privacy copy

Default copy states that local-first tools run in the browser when available and that cloud/API processing requires consent before upload.

Branding

The widget supports partner brand labels while retaining configurable ClearPDF attribution for trust, support, and compliance contexts.

Production checklist

1Required before live rolloutPartner contract with permitted tools, support ownership, data processor terms, and attribution rules.

2Required before live rolloutVerified domain ownership before live allowlist activation.

3Required before live rolloutPer-partner API key or token exchange from partner backend, never from the browser embed.

4Required before live rolloutAbuse, quota, and audit logging tied to partner ID and end-user pseudonymous ID.

5Required before live rolloutSecurity review for CSP, iframe sandboxing, upload size limits, and incident contact routing.