perfox

Site Management ​

Your web chat widget needs to know two things before it can start a conversation: where it's allowed to embed, and whether a visitor is who they say they are. Sites are how you tell Perfox both.

This page is for developers setting up or managing Web Chat embeds. You'll walk away knowing how to create and update sites, rotate signing secrets safely, and understand what Perfox checks on every incoming widget request.

What a site is ​

A site ties together four things: a public identifier (sa_site_live_…, used as the widget's data-site attribute), an allowed_origins list that controls where the embed can load, one or more signing secrets for identity verification, and the agent whose Web Chat Trigger the embed talks to.

You manage sites in the Studio, from the EMBED tab of an agent's Web Chat Trigger node. Everything on this page — create, update, rotate, revoke, suspend, delete — is a button there; there is no API-key endpoint for sites.

CRUD operations ​

Create a site ​

When you create a site you give it a name (up to 120 characters) and an allowed_origins list of 1–20 origins — scheme and host only, like https://www.example.com, with no path. It is bound to the agent whose Trigger you created it from, and you can switch on require_identity_verification. Perfox mints the site and returns:

json
{
  "site": { "id": "…", "site_id": "sa_site_live_…", "name": "…", "secrets": [ … ] },
  "raw_secret": "sa_secret_live_…",
  "embed_snippet": "<script src=… data-site=… ></script>"
}

The raw secret (sa_secret_live_…) is shown once — store it in your environment or secret manager right now. You also get a ready-to-paste embed_snippet. Conversations started through the embed go to the agent the site is bound to.

List / get a site ​

Read-only. Encrypted secret values are never returned — you see the site's identifiers, origins, and secret metadata only, never the raw secret values.

Update a site ​

You can change a site's name, allowed_origins, the agent it is bound to, and the require_identity_verification toggle. The public site_id is immutable and can never be changed after creation.

Suspend / resume a site ​

Suspending a site refuses every widget request that carries its site_id with 403 site_suspended — new conversations and ongoing ones alike — until you resume it. Conversations already recorded are kept, and Resume re-opens the site exactly as it was.

Delete a site ​

Deleting a site is permanent — its site_id stops working and is never issued again, even if you later create a same-named site. There's no undo.

Secret lifecycle ​

The widget's data-site is your public site_id. The signing secrets are the private counterpart — they're what your server uses to produce the user_hash that proves a visitor's identity to Perfox. Two operations manage them.

Rotate a secret ​

Rotation is zero-downtime:

  1. A new active secret is minted (its raw value returned once).
  2. The old secret flips to expiring and is given an expiry of now plus the grace window.
  3. Both active and expiring secrets verify inbound user_hash values during the grace window — no visitor is signed out mid-rotation.

The grace window defaults to 24 hours, and can be set anywhere from 5 minutes to 7 days. Once the window ends, Perfox automatically flips the expiring secret to revoked — no manual cleanup required.

Worked example — rotating Acme Support's widget secret

Asha, the developer at Acme Support, needs to rotate her widget's signing secret after a scheduled credential review.

Setup: She opens her agent, selects the Web Chat Trigger node, goes to its EMBED tab, and starts a rotation with a 6-hour grace window.

Action: Perfox mints a new active secret and returns its raw value once. Asha copies it into her server's environment. She redeploys. The old secret is now expiring and remains valid for 6 hours.

Result: During those 6 hours, any Priya (a customer) who has a session signed with the old key continues without interruption. After 6 hours the old secret revokes automatically.

What just happened: At no point was a visitor's session broken. The grace window gives Asha's server time to pick up the new key before the old one stops working.

Revoke a secret immediately ​

Revoking a secret takes effect immediately with no grace period — use this only on compromise. You cannot revoke the last secret that still verifies (active or expiring); rotate first so a valid signing key always remains.

Secret constraints ​

  • A rotation always leaves exactly one active secret — the new one.
  • Only active and expiring secrets verify signatures. revoked never does.

Identity verification recap ​

Verified sessions sign the visitor identity on your server. The string you sign is <site_id>.<external_id>, HMAC-SHA256'd with the site secret as the key; the hex digest is passed as user_hash in the widget's identify call. Perfox checks that digest against every active and expiring secret for the site (each stored encrypted at rest). Every request is also matched against the Origin allowlist (case-insensitive exact match; a missing Origin is rejected), and the identity path is resolved — anonymous, verified, or self_asserted — with self_asserted requests rejected whenever require_identity_verification is switched on. Full detail: Identity Verification.

You can now create and manage sites, rotate secrets safely, and verify visitor identity end-to-end ​

  • Identity Verification — how to sign user_hash, what the require_identity_verification flag does, and what error codes the site check returns. Read this before going live with verified sessions.
  • Public Widget API — the endpoints that consume X-Perfox-Site and your secrets at runtime.
  • API Keys — the separate server-to-server keying surface for non-widget integrations.