API tokens
An API token lets a program reach your workspace without signing in as a person. It is what you hand to an external system — a CRM, a reporting job, an internal tool — so it can read your workspace's users, conversations and message history through HushChat's ordinary endpoints.
API tokens live on Workspace Settings, which is available to workspace administrators only. If you are not an administrator, the section is not shown to you.
Where to find them
| Platform | How to get there |
|---|---|
| Web | Settings → Workspace Settings → API tokens |
| iOS and Android | Admin tab → Workspace Settings → API tokens |
The section describes itself as "Generate a read-only token to connect an external app (e.g. the CRM control center) to this workspace only. The token is shown once — copy it immediately." With no tokens yet it reads "No API tokens yet. Generate one to connect an external app to this workspace."
Generating a token
- Optionally name it in the field marked "Label (optional, e.g. CRM control center)". The label is only there to help you recognise it later.
- Decide whether the token may change anything — see below.
- Select the button. It reads Generate read-only token, or Generate read-write token once you have ticked the box.
Read-only or read-write
The choice is a single tick-box, Allow this token to make changes, explained as "Needed only by integrations that write — setting workspace roles or assigning agents. Leave off for anything that just reads."
It is off by default, so a token you generate without thinking about it is read-only.
| Read-only | Read-write | |
|---|---|---|
| Reading users, conversations, message history | Yes | Yes |
| Changing anything — roles, agent assignments, settings | Refused | Yes |
A read-only token that attempts a change is turned away with "this API key is read-only". The request does not partly succeed.
Whichever you pick is fixed for the life of that token. To change a token from read-only to read-write, generate a new one and revoke the old.
A read-write token can re-role people and reassign agents. Only tick the box when the integration genuinely writes, and generate a separate read-only token for everything that just reads.
The token is shown once
As soon as the token is created, a panel appears with the secret in it and the warning "New token — copy it now, it won’t be shown again."
- Use the copy icon beside it — the app confirms "Token copied to clipboard".
- Dismiss closes the panel.
Once that panel is gone the secret is unrecoverable. HushChat does not store it in a form it can show you again, so there is no "reveal" and no support route to it. If you lose it, revoke the token and generate another.
Anyone holding the token has the token's access to your workspace. Keep it on a server, never in a browser, a mobile app, a spreadsheet or a chat message. If it has been seen by someone who should not have it, revoke it — do not wait.
What the list shows
Each active token appears as one row:
- A masked stub of the secret — the first few characters and nothing more. It is enough to tell two tokens apart, and not enough to use.
- The label you gave it, if any, followed by read-only or read-write.
There is no created date, no last-used time, and no usage history. The label is your only record of what a token is for, so it is worth filling in.
Revoking a token
Select the bin icon on the row. The app confirms "Token revoked".
Revocation is immediate, has no confirmation step, and cannot be undone. The token stops working at once, the row leaves the list, and anything using that token starts failing straight away — so schedule it, or have the replacement in place first.
To rotate a token: generate the new one, put it into the integration, confirm the integration still works, then revoke the old one.
What a token can reach
- One workspace — its own. The workspace is fixed into the token when it is generated. A token cannot be pointed at another workspace, even by a caller that asks for one.
- Only while it is active. Revoked tokens are dead immediately.
- Read-only tokens cannot change anything, regardless of what the calling program asks for.
The token is sent as the X-Public-Key request header. The integration does not need to name your
workspace — the token already carries it.