API key security: store, rotate and revoke workspace tokens.

What can a workspace token do?

A token that starts hl_sk_ manages one workspace over the REST API and the MCP server. There are no read-only or scoped tokens, and tokens don’t expire, so whoever holds one can:

• change either agent’s greeting, instructions and voice, which callers hear on their next call;
• add knowledge and approve it, so the agent answers from text you never read;
• change the allowed origins and switch customer calls on, letting another site use your free conversations;
• switch human handover on or off for an agent whose team phone is already verified, though it can’t change that number;
• read conversations and automatic insights, including full transcripts and quotes of what callers said;
• create and revoke tokens, including new ones you don’t know about.

Where should tokens live?

Treat every token like a password to your whole workspace.

• In a secret store: your CI’s encrypted secrets, your hosting provider’s environment settings or a password manager. Load the token into an environment variable only when a tool needs it.
• Never in the browser. The widget needs no token, so a token in front-end code or a page’s HTML is always a mistake.
• Never in a repository, including private ones. That covers .env files and MCP configs that live inside a project folder.
• Never in logs, tickets or chat. When you need to refer to a token, use its first 14 characters, which is what the Active tokens list shows.
• Off the command line where you can. A token typed into a command can stay in your shell history and show up in the list of running processes, so pass the header on standard input, as in the example.

# Set KAWLNOW_TOKEN from your secret store first. printf is built into
# the shell, so the token never appears in a command line.
printf 'Authorization: Bearer %s\n' "$KAWLNOW_TOKEN" |
  curl -sS 'https://app.kawlnow.com/api/manage/workspace' -H @-

1. Give each tool its own token.

Create one token for each script, CI job and coding agent, and for each teammate’s MCP client. If you revoke one, nothing else breaks. Kawl Now emails the workspace owner when a token is created or revoked and names it by its first characters, so a register tells you at once whether you expected it.

prefix          used by                      stored in                created     rotate by
hl_sk_1a2b3c4d  docs re-sync workflow        GitHub Actions secret    2026-10-08  2027-01-08
hl_sk_5e6f7a8b  Sam's coding agent (MCP)     Sam's password manager   2026-10-08  2027-01-08
hl_sk_9c0d1e2f  weekly KPI script            CI secret store          2026-10-08  2027-01-08

2. Rotate tokens on a schedule.

Tokens don’t expire, so rotation is a habit you set: every three months, for example, and straight away when someone with access leaves or a token may have been exposed. Rotate in this order and nothing stops working.

• Create the new token under Developers with Create access token, or with POST /api/manage/keys. It’s shown once, so put it straight into the tool’s secret store.
• Switch the tool to the new token, and make one read, such as GET /api/manage/workspace, to prove it works.
• Revoke the old token under Active tokens, or with DELETE /api/manage/keys/{id} using the id from your token list. It stops working at once.
• Check that Active tokens lists only the tokens in your register, and update the register.

3. Catch tokens before they’re committed.

Every token is hl_sk_ followed by 64 lowercase hexadecimal characters, which makes it easy to search for. Your public workspace ID starts with hl_ but not hl_sk_, so these patterns don’t flag your embed code. Search your repository and its history now, and add a pre-commit hook so a token can’t be committed by accident.

# Files in the current checkout that contain a token
git grep -nE 'hl_sk_[0-9a-f]{64}'

# Commits, on any branch, that added or removed one
git log --all --oneline -G 'hl_sk_[0-9a-f]{64}'

#!/bin/sh
# Save as .git/hooks/pre-commit, then run: chmod +x .git/hooks/pre-commit
if git diff --cached -U0 | grep -qE '^\+.*hl_sk_[0-9a-f]{64}'; then
  echo "Commit blocked: it adds a workspace token (hl_sk_)." >&2
  exit 1
fi

What should you check after a suspected leak?

Work through these in order, starting the moment you suspect someone has seen a token they shouldn’t have.

• Revoke the token, and any token under Active tokens you can’t match to your register.
• Create replacements for the tools that need them.
• Check both agents’ greeting, instructions, allowed origins, calls switch and handover switch. Origin, calls and handover changes send an email; greeting and instruction changes don’t.
• Check which sources are approved, and read any you don’t recognise. Approvals send no email.
• Look for a jump in conversations you can’t explain, which can mean another site is using your widget.
• Treat anything the token could read, such as transcripts, as exposed, and follow your own process for personal data.
• Remove the token from git history if it was committed. Revoking it is what makes it harmless; cleaning the history only stops it being found.

Common questions