Integration channel tokens: where they are used and how they are protected
Purpose
Article for security services: a list of places where the integration channel token is used and the protection methods in each of them. The issuance, reissue, and storage formats are described in Integration channel token protection, encryption formats — in Encryption and keys.
The channel has three tokens with different purposes:
-
token_local— platform access token. Presented by an external system to the platform web server (ws role) and grants the channel permissions: roles of its user (opts.userid) and of the channel (opts.roles) according toopts.roles_mode. Protected as a password. Below in the article "token" meanstoken_local. -
token_remote,token_remote2— external system tokens that the platform stores for channel scripts (building requests to the external system). They grant no platform access; protected more weakly, see token_remote and token_remote2.
Protection on the platform side
| Aspect | How it works |
|---|---|
Generation |
By the system only: 12 random bytes and a checksum bound to the domain and channel (32 hexadecimal characters). A token cannot be entered manually or moved from one channel to another. |
Issuance |
The clear-text token is issued once — in the channel creation and reissue response (in the administrator — the "Token shown once" window). It cannot be obtained again via the API, only reissued. |
Storage |
In the DB and domain center memory — ciphertext with the installation key ( |
Request validation |
Channel lookup is by the token SHA-256 hash: web server caches contain no clear-text tokens, and decryption is not performed during validation. An unknown token is remembered for 15 seconds. |
Reading, export, journals |
When reading the channel, in export, events, change journal, and HistoryChanges — ciphertext or a mask with fingerprint |
Platform journals |
A rejected websocket connection token is written as a fingerprint. Command lines of microservices and the product layer installer are written with a mask instead of the token. Exception — the video conferencing server, see [meet]. |
Access restriction |
Lifetime ( |
Guessing |
A failed attempt with an unknown token (REST API, websocket, MCP) is counted against the client address; after a series of failures the address is blocked, as with password guessing. |
Reissue |
Only by the user session (not by token); in bulk — only by the administrator. The previous token stops working immediately (on other sites — within up to 30 seconds), websocket connections using it are closed, channel HTTP subscriptions are deleted; the previous token cannot be restored (token_revoked). |
Where token_local is used
| Place | How it is passed | Notes |
|---|---|---|
REST API ( |
|
Permissions — channel roles. Token reissue, restart with |
Project API in the service script /api/token/v1 |
In the path |
The request URL and headers are passed to the script as is: the token is clear in them. Do not store or log them in the script. |
Token check /api/token/v1/<token>/check, channel files /api/token/v1/<token>/files/… (directory |
In the path (for |
|
HTTP subscriptions /api/token/v1/<token>/subscribe |
In the path (alternative — |
Notifications are sent to the channel |
Recording download /api/download/v1/<token>/<reclink> |
In the path only |
The link contains the token and is passed to external systems (CRM, emails, browsers): the link grants access to recordings until the token is reissued. Use a separate channel with the |
Messenger webhooks /api/im/v1/<token> |
In the path only |
The address is stored in the account ( |
Websocket Token API |
In the path |
The connection is closed when the token is reissued, the channel is disabled or deleted. The |
MCP server |
|
Only |
Hot redundancy: survival_options ( |
|
In the setting — ciphertext with the installation key; in journals — fingerprint. The clear-text token is entered by the administrator during configuration. Addresses |
Product layer microservices (mservices): macros |
|
|
Product layer installer (service channel |
In the installer process command line |
Visible in the process list during installation; in the journal — masked. |
Video conferencing server (service channel |
In the video conferencing server process command line (JSON configuration) |
Visible in the process list of the meet role server; the launch command line is written to the role journal (info level) without masking. |
Service scripts: component Operation, channel entity in request processing script parameters |
Channel entity |
|
Where the token is passed clear
The platform cannot protect the token in the communication channel and on third-party nodes. The token is clear:
-
in the URL path —
/api/token/v1/<token>,/api/download/v1/<token>/…,/api/im/v1/<token>,/ws/token/v1/<token>; -
in the
Authorization: Bearer <token>header — REST API,/api/token/v1,/ws/token/v1,/mcp/v1, hot redundancy requests; -
in the URL and headers passed to the channel request processing script;
-
in the command line of microservice processes (
%TOKEN%), the product layer installer, and the video conferencing server; -
in external system settings: messenger provider cabinets, saved recording links, MCP agent and API client configurations.
Therefore:
-
On external connections TLS is mandatory: HTTPS and WSS. Without TLS the token is visible to anyone who sees the traffic. Unencrypted connections are acceptable only in a trusted network; they can be prohibited for a channel with a client certificate (client_cert_pem).
-
Where there is a choice, pass the token in a header rather than in the path: the path is written to access logs of reverse proxies, balancers, WAF, monitoring systems, and browser history. If a token path is unavoidable (recording download, messenger webhooks), restrict access to the logs of these nodes, disable path logging there, or mask it.
-
Restrict the channel by sender addresses (
remoteipmask), assign it a user with the minimum necessary roles, and use temporary channels for temporary tasks. -
A user with permission to read integration channels sees their settings, including
token_remote;token_localtokens are unavailable to them, but channel permissions (opts.userid) must not be broader than necessary.
token_remote and token_remote2
-
Set by the administrator, not encrypted with the installation key: read clear by everyone who can read integration channels, passed to channel scripts, included in export and the change journal.
-
Do not store secrets whose leak is unacceptable in them without additional protection on the external system side (address restriction, minimal permissions).
What is not protected
-
Leakage of the DB (or its backup) and the installation key together exposes tokens. Without the installation key (format
ha_v=4;…) the token is protected only by the built-in key — set the installation key (general.crypto_kid). -
Change journal and HistoryChanges entries made before version 1.13 may contain clear tokens.
-
A token that got into external node logs, a provider cabinet, or a saved link remains valid until reissue.
-
legacyandinvalidtokens (token_state) work, butlegacytokens are computable from the channel identifier and domain name — reissue them.
Compromise
-
One channel token — reissue the token (reissue), reconfigure external systems, recreate HTTP subscriptions; on suspicion of
token_remoteleakage — change it at the external system. -
Installation key — procedure in Encryption and keys: after re-encryption — mass token reissue (reissue).