How do you send the token?
Put Authorization: Bearer YOUR_WORKSPACE_TOKEN on every request, to every documented REST endpoint under /api/manage and to the MCP endpoint at /api/mcp. Write Bearer exactly like that, with a capital B and one space before the token. The server checks the scheme as written, and anything else returns 401.
There’s no OAuth flow, query-string token or separate API key header. The API also accepts the dashboard’s sign-in session, which is how the dashboard itself calls it, but scripts and coding agents should always use a token.
const response = await fetch('https://app.kawlnow.com/api/manage/workspace', {
headers: { Authorization: `Bearer ${process.env.KAWLNOW_TOKEN}` },
});
if (!response.ok) {
const { error } = await response.json();
throw new Error(`${response.status}: ${error}`);
}
const workspace = await response.json();
console.log(workspace.id);What can a token reach?
The token decides which workspace a request works on, so no endpoint takes a workspace ID.
- One workspace: the one it was created in.
- Everything the API covers in that workspace: both agents’ settings and switches, knowledge and approvals, insights, full transcripts and other tokens. There are no read-only or per-channel tokens.
- Until it’s revoked. Tokens don’t expire, and they stop working at once when they’re revoked or the owner’s account is disabled.
- Not calls. The API has no endpoint that starts a call: visitors start them from the widget, and you run test calls from the dashboard.
- Not the dashboard-only jobs. Phone verification for human handover, an early release, and billing work only in the signed-in dashboard, and the API refuses them when a token is used.
What do authentication errors look like?
Each failure returns 401 with a JSON body that names the problem. Over MCP, the same messages come back as a JSON-RPC error with code -32001 and the same HTTP status.
| Request | Status | Response body |
|---|---|---|
| No Authorization header | 401 | {"error": "Sign in to manage your workspace."} |
| A scheme other than Bearer | 401 | {"error": "Invalid access token."} |
| An unknown or revoked token | 401 | {"error": "Invalid or revoked workspace token."} |
Can a web page call the API with a token?
No. The management API sends no CORS headers, so browsers block requests to it from your web pages, and a token in front-end code could be copied by anyone who opens the page. Keep tokens in server-side code, a CI secret or a trusted MCP client.
Create a separate token for each tool, so you can revoke one without breaking the others. The API key security guide covers storage, rotation and what to do after a leak.