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 to opts.roles_mode. Protected as a password. Below in the article "token" means token_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 (ha_v=5;…​, a separate plug for tokens; without the installation key — ha_v=4;…​ with the built-in key). Ciphertexts of other secrets are not accepted as a token, and the general decryption API does not decrypt the token.

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 *****#<8 hex> (the first 8 SHA-256 characters). A channel of type mcp does not read integration channels (403). Filtering and sorting by token fields are prohibited (422). To the HTTP request processing script (/api/token/v1, /exec) the channel entity is passed with a fingerprint mask instead of the token.

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 (activity_mode, expiry_date), state (state), allowed addresses (remoteipmask), mandatory client certificate (client_cert_pem, closes access over an unencrypted connection), modification prohibition (opts.allow_modify), channel file access (opts.allow_files_api), websocket API restriction (opts.filter_capabilities).

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 (/rest/…​), /exec commands, HTTP subscriptions /rest/v1/service/webhooks, license server collections /rest/v1/model/licserver/…​

Authorization: Bearer <token> header

Permissions — channel roles. Token reissue, restart with cmdline (/rest/v1/master/system/jobs), and decryption (/rest/v1/master/system/decrypts) are unavailable by token (403). An mcp channel token is not accepted here.

Project API in the service script /api/token/v1

In the path /api/token/v1/<token> or in the Authorization: Bearer header (/api/token/v1)

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 :SYNC_DOMAIN_DATA/tokens/, also /rest/v1/fs/targets/token)

In the path (for /rest/v1/fs/targets/token — header)

HTTP subscriptions /api/token/v1/<token>/subscribe

In the path (alternative — /rest/v1/service/webhooks with a header)

Notifications are sent to the channel url without the token. On reissue the subscriptions are deleted.

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 callrec role and address restrictions.

Messenger webhooks /api/im/v1/<token>

In the path only

The address is stored in the account (webhookInfo.url) with the macro {era:token:<channel id>}; the token is substituted only when the platform registers the webhook (max). For vk and whatsapp the address with the token is entered manually in the provider cabinet and stored by the provider.

Websocket Token API /ws/token/v1

In the path /ws/token/v1/<token> or in the Authorization: Bearer header (/ws/token/v1)

The connection is closed when the token is reissued, the channel is disabled or deleted. The connection_info response returns the presented token to the same client.

MCP server /mcp/v1

Authorization: Bearer header only

Only mcp type channels; tokens of this type are accepted only by the MCP server. Secret fields of responses are masked. The token is stored in the agent (MCP client) settings.

Hot redundancy: survival_options (token_local — current system channel token, alternatives.*.token — other system channel token)

Authorization: Bearer header in mware requests to /api/survival/v1/…​, /ws/token/v1, and attachment synchronization

In the setting — ciphertext with the installation key; in journals — fingerprint. The clear-text token is entered by the administrator during configuration. Addresses uris, uris_local with http:// pass the token clear over the network. Synchronized channel tokens are transferred encrypted (more).

Product layer microservices (mservices): macros %TOKENFILE%, %TOKEN%

%TOKENFILE% — a file with 0600 permissions and a random name in the microservice working directory, deleted 10 seconds after launch; %TOKEN% — in the command line

%TOKEN% is visible in the server process list (ps, /proc) — %TOKENFILE% is preferable. In journals the command line is masked. A clear token written into the command is replaced by the domain center with %TOKEN%. On reissue the microservices are restarted.

Product layer installer (service channel product_layer)

In the installer process command line

Visible in the process list during installation; in the journal — masked.

Video conferencing server (service channel service_era_meet)

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

token_local — ciphertext or fingerprint mask; token_remote, token_remote2 — clear.

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_local tokens 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.

  • legacy and invalid tokens (token_state) work, but legacy tokens 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_remote leakage — change it at the external system.

  • Installation key — procedure in Encryption and keys: after re-encryption — mass token reissue (reissue).