Skip to content
Auteryn

Widget Gateway

The widget gateway powers the embedded web widget. Authentication uses widget API keys (wk_pub_ / wk_sec_), then optional JWT for message calls.

Base URL: https://agent-api.auteryn.ai

Authentication flow

Section titled “Authentication flow”
  1. POST /api/v1/widget/init — validate domain + API key; returns session_id, resume_token and the widget config
  2. POST /api/v1/widget/auth?session_id=... — exchange the session’s resume_token for a one-hour JWT
  3. POST /api/v1/widget/message — send chat messages (SSE response); auth via Bearer JWT or X-API-Key
  4. GET /api/v1/widget/history/{session_id} — fetch conversation history (Bearer JWT only; limit defaults to 50, max 100)

PUT /api/v1/widget/session (Bearer JWT only) turns an anonymous session into a known customer: session_id, email, and optionally name and external_id.

The agent is bound to the widget connection through a Loop, not passed in the embed script.

Widget API keys

Section titled “Widget API keys”

Widget keys are separate from org API keys:

Type Prefix Usage
Public wk_pub_... Client-side embed (domain-restricted)
Secret wk_sec_... Server-side only

These keys belong to widgets added before 26 September 2026. Integrations → Web Chat Widget now adds a website on the Website channel, with a site_pub_ key instead.

Example: init

Section titled “Example: init”
POST https://agent-api.auteryn.ai/api/v1/widget/init
X-API-Key: wk_pub_xxxxxxxx
Origin: https://yoursite.com
Content-Type: application/json
{
  "fingerprint": "browser-fingerprint-string",
  "visitor_id": "optional-persistent-visitor-id",
  "referring_page": "https://yoursite.com/pricing"
}

The response includes session_id (required for /auth and /message), config, is_new_session, is_identified and resume_token. Treat resume_token like a password: it is the visitor’s session. Send it back to /init to resume the session.

Example: auth

Section titled “Example: auth”
POST https://agent-api.auteryn.ai/api/v1/widget/auth?session_id=sess_abc
X-API-Key: wk_pub_xxxxxxxx
Origin: https://yoursite.com
Content-Type: application/json
{ "resume_token": "the resume_token from /init" }

Returns { "success": true, "access_token": "...", "expires_in": 3600, "message": "Authentication successful" }. Without a resume_token the call answers 401. When no token can be issued, expires_in is 0 and there is no access_token; send X-API-Key on /message instead.

Example: send message

Section titled “Example: send message”
POST https://agent-api.auteryn.ai/api/v1/widget/message
Authorization: Bearer eyJ...
Content-Type: application/json
Origin: https://yoursite.com
{
  "content": "How do I reset my password?",
  "session_id": "sess_abc"
}

Alternatively, pass X-API-Key: wk_pub_... instead of Bearer JWT.

Domain restriction

Section titled “Domain restriction”

Widget keys are restricted to allowed domains configured on the connection. Requests from other origins are rejected.

Section titled “Related”