Authentication
Every call to the Sessions API and the Files endpoint needs an API key from your workspace. You send it as a bearer token. The key says which workspace you're in and what you may do, so there is nothing else to set up.
Incoming webhooks and the website chat API don't use API keys; see their own rules.
Get a key
An admin creates keys in Settings → API keys:
- Enter a name, like "Mobile app backend".
- Choose Read only or Read and write.
- Click Create key and copy the key. It's shown only once.
Keys start with psk_. See API keys for managing, rotating and revoking them.
Send the key
Put the key in the Authorization header, after Bearer and a space:
GET /api/agents/66f1c2a9e4b0a1d2c3e4f567/sessions HTTP/1.1
Host: peki.ai
Authorization: Bearer psk_your_key
With curl:
curl https://peki.ai/api/agents/66f1c2a9e4b0a1d2c3e4f567/sessions \
-H "Authorization: Bearer $PEKI_API_KEY"
With JavaScript (Node.js 18 or later, or any runtime with fetch):
const res = await fetch('https://peki.ai/api/agents/66f1c2a9e4b0a1d2c3e4f567/sessions', {
headers: { Authorization: `Bearer ${process.env.PEKI_API_KEY}` },
});
if (!res.ok) throw new Error(`Peki API ${res.status}: ${await res.text()}`);
const sessions = await res.json();
The workspace header
You don't need a workspace header: the key belongs to one workspace and every call runs in it. If you do send x-workspace-id, it must be that same workspace, or the call is refused with 403 API key belongs to another workspace.
Access levels
| Key access | Acts as | Allowed |
|---|---|---|
| Read only | Viewer | GET endpoints: list and read sessions, read messages, download files. |
| Read and write | Editor | Everything above, plus start sessions, send messages, upload files, rename, rate and resolve sessions. |
A key never has more than editor rights. Endpoints that need an admin or owner, and endpoints for people only (members, API keys, approvals, the Copilot), refuse every key.
Each endpoint on the Sessions API page lists the access it needs.
Errors
| Status | Message | Why | What to do |
|---|---|---|---|
401 | Sign in required | No Authorization header, or it doesn't start with Bearer . | Send Authorization: Bearer psk_…. |
401 | Invalid API key | The key is wrong, incomplete or revoked. | Check you copied the whole key; create a new one if it was revoked. |
403 | Requires editor role | A Read only key called an endpoint that changes something. | Use a Read and write key. |
403 | Not available to API keys | The endpoint is for people signed in to Peki. | Do it in Peki. |
403 | API key belongs to another workspace | You sent an x-workspace-id for a different workspace. | Leave the header out. |
Example:
{ "statusCode": 401, "message": "Invalid API key", "error": "Unauthorized" }
Keep keys secret
- Call the API from your server, never from a browser or a mobile app. Anyone who can see the key can use it.
- Keep keys in your platform's secret store or environment settings, not in source code.
- Use a separate key per system, so you can revoke one without touching the others.
If you need a chat in a web page without a backend, use the Website chat API, which is built to be public.
Surfaces without an API key
| Surface | Credential |
|---|---|
| Incoming webhooks | The webhook URL itself is the secret (/hooks/whk_…). Turn on signature checks so only the real sender can start the automation. |
| Website chat API | The widget's public key (pw_…) plus a random visitor id. It can only reach that one visitor's own conversation, and only from the sites you allow. |