Skip to main content

​
Advanced Security

Warpy can protect widget runs with short-lived signed widget tokens. This is the flow:
  1. Enable Require signed widget token
  2. Copy the shared Warpy API Key from API Config
  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 Warpy API Key
Warpy -> Customer backend  : { token }
Customer backend -> Widget : { token }
Widget -> Warpy            : WS /widget/session
Widget -> Warpy            : first chat.request includes widgetToken
The widget does not put this token in the websocket URL. It sends the token in the first chat.request payload after connecting.

​
What the API key is for

The Warpy API Key is a server-side secret. It should never be exposed to the browser. Warpy uses it to mint short-lived widget JWTs and to authenticate direct control-plane API access.

​
Staged changes

Advanced Security uses a draft-and-deploy flow:
  • enabling signed tokens is staged
  • changing the refresh endpoint path is staged
  • API key rotation is not staged here
  • nothing about widget security 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.

​
Where key management lives

The Warpy API Key is managed only from API Config:
  • copy the current key
  • rotate the key
  • copy the coding-agent prompt
The Overview page only shows the masked key and a one-click copy prompt. The Agent page only references the shared key.

​
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.