Connect widget

The Polymorfa Connect widget is a hosted pairing flow for QR, pairing-code, and Cloud API onboarding. Your backend creates a widget session; your frontend embeds or redirects to the returned URL. The API never exposes your organization or project credential to the browser.

Manage saved settings

In the Console, open team or project Settings → Embedded Signup. You can enable the widget, select connection modes and methods, allow exact redirect URLs and embed origins, and configure its name, colors, shape, theme, watermark, and history-sync behavior. Server automation can read the effective settings with GET /v1/widget and save changes with PUT /v1/widget. Send projectId to manage settings for one project; omit it to manage the organization defaults. These Platform API operations accept an organization key with widget permission or a signed-in Console bearer. They reject project and client tokens. PUT /v1/widget accepts any subset of these fields:

Field	Type	Allowed values or limits
`projectId`	UUID	Optional project-specific settings target
`enabled`	boolean	Enables or disables widget session creation
`modesAllowed`	array	`embedded`, `redirect`; 1–50 unique values
`methods`	array	`qr`, `pairing`, `cloud-api`; 1–50 unique values
`allowedRedirectUris`	URL array	Up to 50 exact callback URLs
`allowedOrigins`	origin array	Up to 50 origins without paths or credentials
`businessName`	string	Up to 120 characters; empty removes the override
`accent`	string	Six-digit hex color such as `#6A3DE8`
`theme`	string	`light`, `dark`, or `system`
`hideWatermark`	boolean	Shows or hides the Polymorfa footer
`colors`	object	Optional `light` and `dark` six-digit hex palettes
`shape`	string	`square`, `rounded`, `pill`, or `null`
`radiusPx`	number	`0`–`999`, or `null`
`historySync`	string	`ask`, `force_on`, or `force_off`

Use HTTPS redirect URLs and origins. Origins must contain only the scheme and host. Stored settings take precedence over protected per-session values when you create a widget session. Call POST /api/widget/sessions from your backend with an organization key that has widget:create. Widget creation is a human-controlled operation; project tokens are rejected even when they carry similarly named scopes.

curl -X POST https://api.polymorfa.com/api/widget/sessions \
  -H "Authorization: Bearer $TITAN_ORGANIZATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "embedded",
    "methods": ["qr", "pairing"],
    "businessName": "Acme",
    "allowedOrigins": ["https://app.acme.example"],
    "theme": "system"
  }'

{
  "success": true,
  "data": {
    "widgetUrl": "https://polymorfa.com/widget/connect?ct=...",
    "redirectUrl": "https://polymorfa.com/widget/connect?ct=...&fullscreen=1",
    "clientToken": "titan_ct_...",
    "session": "widget-5c9f9f171e29"
  }
}

The generated client token lasts 15 minutes and is restricted to the new session and the widget actions. Do not log or persist the token or either URL.

Request fields

Field	Type	Notes
`mode`	`"embedded" \| "redirect"`	Defaults to `embedded`. Redirect mode requires `callbackUrl`.
`projectId`	`string`	Applies project-specific widget settings when using an organization key.
`methods`	`("qr" \| "pairing" \| "cloud-api")[]`	Connection methods to show.
`businessName`	`string`	Business name displayed in the flow.
`historySync`	`"ask" \| "force_on" \| "force_off"`	Controls the history-sync choice.
`sessionName`	`string`	Optional stable session name; one is generated when omitted.
`callbackUrl`	URL	Must exactly match a configured redirect URI.
`allowedOrigins`	URL array	Origins allowed to embed the flow; stored Console settings remain authoritative.
`theme`	`"light" \| "dark" \| "system"`	Appearance override.
`accent`	hex color	Six-digit color such as `#6A3DE8`.
`prefillPhone`	string	6–15 digits, with an optional leading `+`.
`autoSubmitPhone`	boolean	Skips phone entry when `prefillPhone` is set.
`analytics`	object	Optional `posthogKey` and `posthogHost`.
`metaApp`	object	Optional Cloud API `appId` and `appSecret`. Keep this call server-side.

Project configuration controls whether the widget is enabled, allowed modes, redirect URIs, origins, branding, shape, watermark, connection methods, and history-sync behavior. Protected stored settings take precedence over request values.

Embed the returned URL

Use the returned widgetUrl directly in an iframe, or load the helper served by the API:

<div id="polymorfa-connect"></div>
<script
  src="https://api.polymorfa.com/widget/embed.js"
  data-widget-url="WIDGET_URL_FROM_YOUR_BACKEND"
  data-container="#polymorfa-connect"
  data-theme="system"
  data-width="400"
  data-height="540">
</script>

The helper emits titan:widget postMessage events and supports connected, error, and cancelled. The global Titan.createWidget({ url, container, onConnected, onError, onCancelled }) compatibility API provides programmatic mounting.

Always fetch widgetUrl from your own authenticated backend. Never put an organization key in browser code.

Redirect flow

Set mode to redirect, supply an allowlisted callbackUrl, and send the browser to redirectUrl. Redirects are closed by default until exact callback URLs are configured for the project.

Cancel a pending session

DELETE /api/widget/sessions/{session} revokes the widget rules and cancels a pending connection.

Cross-device handoff

A widget client token for the same session can call POST /api/widget/sessions/{session}/handoff. The response contains a handoffUrl, an SVG meta-QR, and expiresAt. The receiving device opens the URL and polls GET /widget/handoff/{token}/state for the current WhatsApp QR and session status. The handoff token is the bearer credential and expires within 15 minutes. The handoff becomes unusable after it is consumed or invalidated; a copied token remains sensitive until it expires. State responses use Cache-Control: no-store so browsers and shared caches do not retain the QR or session status. Treat the token like the widget URL and never log it.

Security model

The organization key remains on your server; project tokens cannot create widget sessions.
The browser receives a session-bound titan_ct_ token with widget-only actions.
Redirect URLs and embed origins are checked against project settings.
Handoff state uses a short-lived signed token in the URL; no credential exchange occurs on the second device.
Cancelling a session revokes its client-token rules.

Get started

Console

Inspector

Sandbox

Integrations

Manage saved settings

Create a widget session

Request fields

Embed the returned URL

Redirect flow

Cancel a pending session

Cross-device handoff

Security model

Where to go next

Client tokens

Webhooks

​Manage saved settings

​Create a widget session

​Request fields

​Embed the returned URL

​Redirect flow

​Cancel a pending session

​Cross-device handoff

​Security model

​Where to go next

Client tokens

Webhooks

Manage saved settings

Create a widget session

Request fields

Embed the returned URL

Redirect flow

Cancel a pending session

Cross-device handoff

Security model

Where to go next