Authentication

Peeve has two kinds of API key. Confusing them is the most damaging mistake you can make with this API, so this page is worth reading in full before you write any integration code.

The two keys

Publishable — pk_…

Public by construction. It ships in your page source, where any script on the page can read it. That is expected. What controls access is the request origin, not secrecy.

Secret — sk_…

A bearer credential with full workspace authority. Server-to-server only. Never in a browser, never in client-side code, never in a repository.

Which key reaches what

Endpoint	Publishable	Secret
`POST /v1/users`	Rejected	Required
`GET`/`POST /api/killswitch`	Rejected	Required
The widget’s own calls	Required	Rejected
`GET /api/agent/{pk}/{artifact}`	Required, in the URL path	Rejected
`GET`/`POST /api/mcp/{workspaceId}`	Not used	Not used

The gate is exact in both directions. /v1/users resolves your key with a publishable key explicitly excluded, so a pk_… lifted from a page cannot reach it — and it emits no CORS headers at all, so it is not callable from a page by construction. Equally, the widget’s endpoints resolve with a secret key excluded, so a secret key sent there returns 401.

There is no endpoint where either key works. If you are unsure which one an endpoint needs, the table above is the answer, and the API reference states it per operation.

How to send a key

Secret key — as a bearer token, or in the Peeve header:

curl https://api.peeve.ai/v1/users \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id": "user_8412"}'

curl https://api.peeve.ai/v1/users \
  -H "X-Peeve-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id": "user_8412"}'

Publishable key — you do not normally send this yourself. It goes in your widget script tag, and the widget handles the rest:

<script
  src="https://cdn.peeve.ai/widget.js"
  data-publishable-key="pk_live_xxx"
  defer
></script>

It also appears as a path segment on the agent artifact URLs, which is safe because the key is public by construction:

curl https://api.peeve.ai/api/agent/pk_live_xxx/llms.txt

Sending an Origin header matters. From a browser it is set for you. From cURL or a server you must set it yourself, or the origin check will refuse the request in production.

What a key resolves to

A key resolves to exactly one workspace, and that is the tenant boundary. The workspace id comes from the validated key — never from anything in the request body — so nothing a caller sends can reach another workspace’s data. Key lookups are cached briefly (20 seconds). This is what bounds how long a revoked key or a flipped kill switch takes to take effect: within 30 seconds, and immediately for the kill switch, which clears the cache when it flips.

Creating and rotating keys

Where keys come from, how they are stored, and how to rotate one safely.

Origins

The exact rule that makes a public key safe to publish.

Get started

Authentication

Widget

MCP server

Agent artifacts

Reference

Authentication

The two keys

Publishable — pk_…

Secret — sk_…

Which key reaches what

How to send a key

What a key resolves to

Next

Creating and rotating keys

Origins

​The two keys

Publishable — pk_…

Secret — sk_…

​Which key reaches what

​How to send a key

​What a key resolves to

​Next

Creating and rotating keys

Origins

The two keys

Which key reaches what

How to send a key

What a key resolves to

Next