Secure your embed integration

Use your host login session to establish identity, an origin allowlist to restrict browser access, and server-side checks to protect tools. This page configures those boundaries. See Test your integration for scenarios and the go-live checklist for release verification.

Preparation and responsibilities

You need Dashboard access to manage the service agent, a host backend, and permission to change website response headers. Configure the embed policy and token issuance before reviewing these responsibilities.

Protect identity and credentials

Your backend uses PRAXIS_API_KEY to issue a short-lived embed token. Send only the required token to the browser. Revalidate the host login session for issuance and renewal. Never let a request body's external_user_id establish identity. Keep API Keys and embed tokens out of URLs, HTML, and logs.

Kit's transport holds its token in memory. Anonymous access also uses a visitor_secret, which Kit attempts to save in localStorage to retain visitor identity. It falls back to page memory when storage is unavailable. A publishableKey is public; a visitor_secret is private. Anonymous identity is not a logged-in account on your website.

On logout, stop issuance, remove the chat component, and revoke the relevant credentials from your backend. Clearing the page is not revocation. Blocking an end user prevents new issuance and revokes that user's existing tokens. Kit can obtain a token before expiry; Hosted does not automatically renew. See Embed tokens and users.

The model may repeat instructions, system_message, page context, or tool results. Include only information the current user may access. Never pass secrets or another user's data as context.

Restrict page origins

The origin allowlist can currently only be configured in the Dashboard. Open 服务智能体 → your agent → 接入与配置 → 配置 → 安全 (Service agents → your agent → Integration and configuration → Configuration → Security). Click 添加来源 (Add origin), enter an origin such as https://shop.example.com, then 保存安全设置 (Save security settings). Expected: the saved message confirms no new agent version was created.

allowed_origins permits at most 50 entries. Enter origins without paths, queries, or fragments. Regular origins require HTTPS. https://*.example.com matches one subdomain level, not the root or deeper subdomains, and does not support ports. 允许 localhost is for local HTTP development and defaults to off.

During issuance, use allowed_origins to select a nonempty subset of policy entries, matching them exactly. Do not use an empty array to mean “deny all”: token validation falls back to the policy allowlist. Changing a policy does not revoke issued tokens. Revoke credentials when access must be withdrawn immediately.

A disallowed origin returns HTTP 403 with EMBED_ORIGIN_NOT_ALLOWED. Correct the configuration before reconnecting. Origin checks constrain browsers; non-browser requests without Origin bypass this check. It does not replace token authentication.

Protect tool access

Your MCP server must authenticate the platform caller before treating X-Praxis-External-User-Id as the end-user identity. The platform also sends X-Praxis-Agent-Id and X-Praxis-Session-Id. Sessions without an end user do not carry these identity headers.

Reject requests missing required identity. Scope every query to that user, and verify ownership and business state before changing an order. Do not trust a model-supplied user ID or a public request merely because it contains identity headers. Authenticate the caller using MCP-configured headers before trusting platform-supplied identity.

Confirmation cards check intent; clicking allow does not grant data access. Client tools and page context come from the browser and cannot enforce authorization.

Protect the host page

This Develop response-header example assumes initialization scripts live in same-origin JavaScript files and Kit loads from its CDN. Narrow image and other sources to your site's needs. If initialization remains inline, add a CSP nonce or hash for that script.

Content-Security-Policy: default-src 'self'; script-src 'self' https://kit-develop.praxisusercontent.com; style-src 'self' 'unsafe-inline' https://kit-develop.praxisusercontent.com; connect-src 'self' https://api-develop.deepraxis.com https://kit-develop.praxisusercontent.com; frame-src https://chat-develop.praxisusercontent.com; font-src 'self' https://kit-develop.praxisusercontent.com data:; img-src 'self' https: data: blob:; frame-ancestors 'none'; base-uri 'self';

Kit themes use inline styles, which this policy allows. Connection sources must match api.url. frame-src permits loading the hosted iframe; frame-ancestors 'none' prevents other sites from embedding your host page.

Platform iframe ancestors come from the allowlist; an empty list prevents framing. Hosted cannot be framed. Kit's open Shadow DOM isolates styles, but scripts on the same page can read it. Avoid sharing the chat page with untrusted scripts.

For CDN integrity checks, copy the actual fixed-version URL and integrity generated by the Dashboard, retaining crossorigin="anonymous". Do not attach a fixed hash to the floating /v1/ URL or use an illustrative hash as a release value.

Verify and continue

Reload from an allowed website and send a message. Inspect the host response's CSP in browser Network tools. Console should show no CSP failures loading Kit or connecting to the API. Confirm the issuance route returns only short-lived credentials and that tool access is scoped to the logged-in user.

Test your integration · Go-live checklist · Embed limits and errors.