API reference
API keys: secret and publishable
The two kinds of SentientOne key, where to find them, where each one may be used, and what to do if a secret key leaks.
Reference2 min readUpdated 23 October 2026
SentientOne has two kinds of key. Your secret key lets a server call any of your agents through the API. A publishable key lets the website widget chat with one agent, from the websites you allow. Your model provider's key (OpenAI, Anthropic, Google Gemini or Groq) is a third, separate thing: see LLM keys.
The two keys side by side
| Secret key | Publishable key | |
|---|---|---|
| Looks like | sk-so- followed by 58 hex characters | pk-so- followed by 40 hex characters |
| How many | One per account, made when you sign up | One per agent, made the first time you open its Deploy tab or the Widget page |
| Sent as | X-Api-Key header | data-widget-key on the widget script (sent as X-Widget-Key) |
| Can do | Chat with any of your agents, run workflows, add knowledge, read traces and analytics | Chat with its own agent only, while it is active, from allowed websites |
| Where it may live | Your servers and secret stores only | Public web pages |
| Rotate | Not self-serve: email support if it leaks | Rotate on the Deploy tab; the old key stops within 10 seconds |
Where to find them
- Secret key: open API keys in the app's sidebar (under Configure). The page shows the key masked, the agent ids, ready-made code samples and a Try it panel that sends a real request. The agent's Deploy tab shows it too.
- Publishable key: open the agent, then Deploy. The embed code there already has the key filled in. See Install the widget.
Rules for the secret key
- Never put it in a web page, a mobile app, a browser extension or a public repository. Anyone who has it can spend your credits and read your agents' traces.
- Keep it in an environment variable or a secret manager, and call the API from your backend. For a browser chat, proxy through your own server (there's an example in Code examples) or use the widget.
- The widget refuses secret keys outright (
401 SECRET_KEY_NOT_ALLOWED), so a copied secret key can't be used to run someone else's embed. - There are no scopes: the key reaches every agent on your account.
If your secret key leaks
There's no self-serve way to rotate the account's secret key yet. Email support@sentientone.ai straight away with your account email, and remove the key from wherever it was exposed. Until then you can pause affected agents on their Settings tab (a paused agent turns every request away with 403 AGENT_INACTIVE).
Questions
Can I have one key per environment?
No, there's one secret key per account. Use separate accounts if you need fully separate staging and production keys.
Does the publishable key need to be kept secret?
No. It's designed to be public. It only reaches one agent, only from your allowed websites, within 120 requests a minute per key and 12 per visitor.
Where does my model provider key go?
On the LLM keys page or the agent's Settings, never in the API call (unless you deliberately override it for one request with the X-Llm-Key header).
Still stuck?
Email us with what you tried and any request id. A person replies.