Embed tokens and users

Embed tokens let end users access a specific agent and their own sessions. For signed-in users, your backend issues the token and the browser consumes it. This guide covers identity, expiration, refresh, and single-token revocation.

You need a service agent in your organization, a saved embed policy, and a backend API key. Save the policy under 接入与配置 → 配置 → 安全 in the Dashboard; it can currently only be configured there. Examples use Develop. See Embed in a web page for a complete integration or Hosted for single-use redirects.

Identity and access

Your backend authenticates users through your login system, then supplies a stable external_user_id. The same organization, agent, and identifier refer to the same end user. This is neither an organization member ID nor a display name. Identifiers contain 1–128 characters: letters, digits, underscores, periods, colons, @, and hyphens.

Refreshing a token does not change identity. When accounts change, remove the old component and create one for the new identity. UI confirmation buttons do not replace server-side account authorization in your tools.

Issue a token

Production issuance calls POST /agent/v1/embed_tokens from your host backend. These standalone server checks use test user customer_123. Your actual host must derive the ID from a verified login session, never a browser assertion. The Dashboard's 试用调试 → 模拟 → 重新签发 is for identity debugging only.

set -o pipefail
curl --fail-with-body --silent --show-error \
  -X POST https://api-develop.deepraxis.com/agent/v1/embed_tokens \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"agent":"agent_REPLACE_ME","external_user_id":"customer_123"}' \
  | jq '{id, expires_at, has_token: (.token | type == "string")}'

Expected: HTTP 201 with id, token, and expires_at. Use id to revoke this issuance, token as the browser credential, and expires_at as its ISO 8601 UTC expiration. Examples print only redacted check results. Every call creates a new grant; repeated issuance is not idempotent.

Omitted ttl_seconds uses the policy default. The range is 60 seconds through the smaller of the policy maximum and 3600 seconds. budget_cents cannot exceed the policy session-budget maximum. allowed_origins must be a subset of existing policy entries. Version selection uses explicit version, then the policy's pinned version, then latest. The selected version is fixed at issuance. See the API reference for all fields.

Refresh and end access

Kit calls getToken(current) with null initially and the current token on refresh. Use this callback for api.getToken in the quickstart. Your endpoint verifies that the user is still signed in before returning a fresh token.

async function getToken(current) {
  const response = await fetch("/api/praxis-token", {
    method: "POST", credentials: "same-origin", cache: "no-store",
  });
  if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
  const data = await response.json();
  if (typeof data.token !== "string" || !data.token) throw new Error("Missing token");
  return data.token;
}

The callback does not need to send the current token to prove host identity. Kit schedules calls and keeps tokens in memory. Do not hard-code a fixed token. Expected: refreshing preserves access to the same user's sessions.

On sign-out, end the host session and remove the old Kit element. Removal closes its connections but does not revoke issued tokens on the server. Revoke separately when the old credential must stop working immediately. Hosted has no equivalent refresh path; users return to the host after expiration.

Anonymous visitors

For public questions without login, open 接入与配置 → 密钥 → 可公开 key → 新建可公开 key. Configure anonymous limits and budget, and copy the complete value shown only once. Manage allowed origins under 配置 → 安全. These settings can currently only be configured in the Dashboard. A publishable key cannot replace a backend API key.

Save this standalone page as index.html. Replace PRAXIS_PUBLISHABLE_KEY with your actual publishable key and serve it from an allowed origin. It does not need a signed-in host token endpoint. Do not also configure getToken.

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Public documentation assistant</title>
<script type="module" src="https://kit-develop.praxisusercontent.com/v0.2.8/praxis-kit.js" integrity="sha384-vey+VZZcFIWJq9Fmv/nmLxspKtXRiL8XiDOfg2g2QFvwZi5MA+tkiQvPBtoMS8eU" crossorigin="anonymous"></script>
<praxis-agent style="display:block;height:600px;width:100%"></praxis-agent>
<script type="module">
  await customElements.whenDefined("praxis-agent");
  document.querySelector("praxis-agent").setOptions({
    api: {
      url: "https://api-develop.deepraxis.com",
      publishableKey: "PRAXIS_PUBLISHABLE_KEY",
    },
    agent: { name: "Documentation assistant" },
  });
</script>
</html>

Kit sends publishable_key to POST /agent/v1/embed_tokens/anonymous, adding an existing visitor_secret on later requests. No API key is required. Success returns HTTP 200 with token and expires_at; only new visitors also receive visitor_secret. Browsers cannot choose external_user_id, budget, instructions, or Hosted options.

Kit saves the visitor credential in local storage, falling back to page memory when storage is unavailable. Do not publish or share it. Expected: the same browser storage preserves visitor identity across refreshes; separate browser storage produces separate identities. Anonymous identity does not authorize access to account data such as orders.

Inspect and revoke

Revoke only the token whose access should end. These paths perform the same task.

Expected: revocation returns a record with revoked_at; repeated revocation returns the original record. Streams using that token receive session.error with EMBED_TOKEN_REVOKED, then close. Other tokens are unaffected. For user-wide revocation, blocking, and unblocking, see Manage end users.

Errors and next steps

Revalidate host login after expiration. Stop the original access after revocation. Correct configuration for disallowed origins; ask an administrator to handle blocked users. Do not repeatedly issue tokens to bypass denial. See Embed limits and errors for codes, HTTP statuses, and recovery conditions.

• Pass context
• Manage end users
• Open hosted chat
• Agent API reference