Skip to main content

​
Advanced Security

Warpy can protect widget chat calls with short-lived signed widget tokens. This is the flow:
  1. Enable Require signed widget token
  2. Generate a Widget API Key
  3. Implement a customer-owned refresh endpoint such as POST /widget-token
  4. Have that endpoint call Warpy’s POST /widget-token
  5. Return { "token": "<jwt>" }
  6. Deploy the staged changes
Widget -> Customer backend : POST /widget-token
Customer backend -> Warpy  : POST /widget-token with Widget API Key
Warpy -> Customer backend  : { token }
Customer backend -> Widget : { token }
Widget -> Warpy            : /widget/chat with Bearer widget token

​
What the API key is for

The Widget API Key is a server-side secret. It should never be exposed to the browser. Warpy uses it to mint short-lived widget JWTs for a specific agent.

​
Staged changes

Advanced Security uses a draft-and-deploy flow:
  • enabling signed tokens is staged
  • changing the refresh endpoint path is staged
  • generating or rotating the API key is staged
  • nothing goes live until you click Deploy Changes

​
Refresh endpoint requirements

The configured refresh endpoint path must:
  • start with /
  • be a path, not a full URL
  • live on the base URL you selected for that environment
Warpy also includes a local helper route, POST /test-widget-token, for non-production testing when TEST_WIDGET_TOKEN_API_KEY is configured.

​
Rate limits

User rate limits let you cap actions per user by IP address. You can set:
  • daily limit
  • monthly limit
When a user exceeds the configured limit, the widget hides until the limit resets.

​
Important note

If your customer backend already has an authenticated server-side session, the refresh endpoint can stay protected by that existing auth layer. The widget only needs the returned short-lived JWT, not the server-side secret itself.