Publishable widget keys (pk-so-)

The widget never carries your secret sk-so- key. Each agent has one publishable key, pk-so- followed by 40 hex characters, made the first time you open its Deploy tab or the Widget page. Anyone can read it in your page's source; it is built so that doesn't matter.

What a publishable key can do

• Chat with its own agent only. Naming another agent gets 403 WIDGET_KEY_SCOPE.
• Only while the agent is active (otherwise 403 AGENT_INACTIVE).
• Only from your allowed websites (otherwise 403 ORIGIN_NOT_ALLOWED).
• Only continue its own agent's conversations.
• Spend your credits, 1 per reply.

What it can't do

• Override the system prompt, send a model key or reach a paused agent.
• Call the API's other endpoints: knowledge, traces, analytics or workflows.

The reverse holds too: a secret key sent on the widget path is refused with 401 SECRET_KEY_NOT_ALLOWED, so a leaked server key can't be put to work in someone else's page.

Limits

Limits are checked before a credit is spent, so a script hammering your widget can't drain your balance quickly. Visitors over a limit see "Too many messages. Please wait a moment and try again."

Rotate the key

1. 1

   Open the Deploy tab

   Open the agent's Deploy tab or the Widget page.

2. 2

   Rotate

   Choose Rotate key and confirm. Allowed websites are kept.

3. 3

   Update every website

   Copy the new embed code and replace the old tag everywhere. The old key stops working within 10 seconds, so the widget is down on any page still using it.