FruxonDocs
ApiEmbed widget

Opens a live session for a web visitor from a publishable embed key.

Validates the key + embedding origin, provisions/reuses the anonymous visitor, and returns the session id + short-lived session token (the bearer credential for every other call) plus the agent's presentation.

POST
/v1/embed/sessions

Request Body

The embed key, optional visitor key and embedding origin, and an optional signed visitor identity.

embedKey?string

The publishable embed key from the snippet.

visitorKey?string|null

Stable per-visitor key the client persists (localStorage) for return-visit continuity. Optional — when omitted a fresh visitor is minted and returned.

origin?string|null

The embedding page's origin. The iframe is served from Fruxon's origin, so the request's own Origin header is Fruxon's — the client reports the parent site here (e.g. from ancestorOrigins). Falls back to the Origin / Referer header when absent.

identity?

An identity the embedding site vouches for, signed with the widget's identity secret. Omit for an anonymous visitor. Present-but-unverifiable is refused rather than downgraded, and a widget in Fruxon.Model.EmbedWidget.EmbedAccessMode.RequireIdentity refuses a session without one.

idToken?string|null

An OIDC ID token for a widget backed by an OIDC_ISSUER trust anchor — the signed-in user's own Firebase/OIDC token, passed straight from the client with no host backend involved (design jit-provisioning.md §4.2). Verified at session-init against the anchor's pinned issuer and audience; present-but-unverifiable is refused, exactly like a bad Fruxon.Model.EmbedWidget.EmbedInitRequest.Identity hash.

[key: string]?never

Response Body

curl -X POST "https://api.fruxon.com/v1/embed/sessions" \  -H "Content-Type: application/json" \  -d '{}'
{
  "sessionId": "string",
  "sessionToken": "string",
  "expiresInSeconds": 0,
  "visitorKey": "string",
  "agent": {
    "displayName": "string",
    "avatarFileId": "string"
  },
  "greeting": "string",
  "suggestedPrompts": [
    "string"
  ],
  "themeJson": "string",
  "hideBadge": false,
  "customCss": "string"
}
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}