Integration channel (integration_point)
Description
The integration channel mainly defines the processing point for HTTP(S) webhooks arriving from external systems, as well as a point for WebSocket connections with predefined rights.
In some cases the integration channel defines the external system URL for sending HTTP requests to it from scripts.
Supports streaming asynchronous processing of messages arriving from WebSocket connections and sending responses and events back to them.
Supports creating project APIs using service scripts.
A WebSocket connection to the integration channel is made with token_local specified directly in the URL or in the Authorization header. More.
An HTTP(S) connection to the integration channel is made with token_local. Used for accessing project APIs, as well as for downloading call recordings and messenger webhooks.
Can be permanent or temporary. For temporary ones, set the date and time until which the integration channel is active. When the activity date is exceeded, the system automatically moves the integration channel to the expired state.
Secret fields in responses for channels of type `mcp`: password, key, and token values of domain center objects are returned as `+*****+` — in REST API collections (list, element, `mask`/`flat` field selection, create and update responses, `dry_run` check) and in the change log. An empty value is returned as is.
Secret fields: user password; SIP account `pwd` and `credentials.*.pwd`; provider `pwd` and private key bodies in `certificate_pem`; domain `dbpwd`; passwords and keys in storage `params`; integration channel `token_local`, `token_remote`, `token_remote2`; domain setting secrets (`yandex_cloud`, `sber_salute`, `azure_cloud`, `record_asr_options`, password in `project_postgresql_connstr`, `billing_options`, `survival_options` tokens, `wakeup_device_options`, `snmp_options`, private key bodies `certificate_pem`, `meet_cert_pem`, `meet_turn_cert_pem`); passwords in configuration `content`.
Filtering and sorting by a secret field, as well as a computed property name (`["property", <expression>]`) in filter and sort, are rejected (422).
The value `+*****+` sent back to a secret field on update does not change the stored value if the fields determining the secret recipient (address, port, login, URL, account, etc.; for a connection string and PEM, the rest of the value) are not changed. Otherwise, as well as in list elements and on creation, error 422: the secret must be set again. Exception — SIP account `credentials`: the element is matched with the stored one by `login` (including a different order); a new or changed `login` with `+*****+` is error 422. Likewise (422) when changing these fields without passing the secret: the stored secret is not sent to the new recipient.
Secret properties of DMS classes (`email/Accounts`, `im/Accounts`, `oauth/Providers`, etc.) are stored encrypted and returned as ciphertext (more); non-secret fields of these classes (e.g. `options.proxyUrl` with proxy credentials) are returned as is.
Unavailable (403): `/rest/v1/master/currentconfiguration`, classes `platform/log/HistoryChanges`, `oauth/Requests`, `licserver/Licenses`, `licserver/Syncs`, `system/PwdResetRequests`, `system/Invites`, `system/SelfRegisterRequests`, `/rest/v1/uc/sipusers/<id>/device` (device manager response), integration channels `/rest/v1/service/integration_points` (read and modify), and the encryption report `/rest/v1/domain/crypto_values`.
Through the MCP server, the `mcp` channel reaches only the REST API (`/rest/…`, with masking and restrictions above) and the `/api` commands needed by tools (only `GET`; the list is in MCP server). Other paths (`/api/crud`, other `/api/admin` and `/api/monitor` commands, `/api/token`, `/exec`, proxied applications, etc.) — 403.
Limitations
-
The collection is available in any domain.
-
Licensed by a quantitative parameter: a license is consumed for the channel type.
Fields
{
"id": uuid,
"code": str,
"type": str,
"activity_mode": str,
"state": str,
"expiry_date": date,
"token_local": str,
"token_state": str,
"token_remote": str,
"token_remote2": str,
"url": str,
"recv_svcscriptcode": str,
"send_svcscriptcode": str,
"recv_svcscriptcode_ws": str,
"send_svcscriptcode_ws": str,
"opts": {
"allow_files_api": bool,
"comment": str,
"issync": bool,
"recv_timeout": int,
"roles": ["special01"],
"userid": "37a85e8-1a01-835f-4490-e78015a20052",
"title": str
},
"ext": {
"ct": date,
"lwt": date
}
}
| Specification | Description |
|---|---|
Field: |
Identifier. Can be specified at creation, otherwise generated by the system. |
Field: |
Code. Used to associate with other entities and script components. |
Field: |
Integration channel type. |
Client certificate required to connect to the integration channel via token_local. An integration channel for which a client certificate is specified here blocks access for unencrypted connections (if unencrypted connections are allowed by web server settings). TLS connections to the protected port of the ws instance are by default handled according to the tls_mode policy, which may allow or disallow connections without a client certificate. The certificate can be specified in the following ways:
The PEM content must contain at least the certificate itself. But it may additionally contain the private key and optionally chain certificates.
|
|
Field: |
Integration channel activity mode.
|
Field: |
Integration channel state.
The "expired" state is set by the system automatically when the activity time is exceeded (specified in the "Active until" field). |
Field: |
Date and time until which the integration channel is active. When the specified date is reached, it is moved to the expired state. |
Local token. |
|
Token state:
|
|
Field: |
External token. |
Field: |
Additional external token. |
Mask of the request sender IP address allowed to access the API through this token.
|
|
Code of the service script run to process an incoming HTTP request using token_local. Allows implementing project APIs. Endpoint for accessing the script: The following parameters are passed to the service script (available in expressions via the startparam(N) method):
The service script has local string variables whose values determine the HTTP response:
The body format can be arbitrary and is determined by the Content-Type header. |
|
Field: |
Code of the service script run to send an HTTP request to the channel from chatbot scripts |
Code of the service script run to process an incoming WebSocket message using token_local. Allows implementing project APIs. Within a WebSocket connection to the token, the method for accessing the script API: ["message", {"qid": …,"data": …, …}]. The following parameters are passed to the service script (available in expressions via the startparam(N) method):
The service script has local string variables whose values determine the HTTP response:
Response message format:
[
"message_result",
{
"qid": ...,
"success": true,
"data": ...
}
]
|
|
Field: |
Code of the service script run to send a WebSocket message to the channel from chatbot scripts |
Field: |
Data provider URL. Used when building the full URL in the "Web request" component of scripts. Relevant for domains with types that preclude specifying full addresses in the properties of the "Web request" component. However, creating arbitrary domain types is disabled in all builds. |
Field: |
|
Field: |
Permission to work with files. Available only for type= |
Modifications allowed. When
Other requests, including check without saving ( The option does not protect if the channel user can create integration channels or reissue their tokens: such channels grant access, including with allowed modifications. Channel rights are determined by the user’s roles (opts.userid) and the channel’s roles (opts.roles) according to opts.roles_mode — assign a user with minimally necessary roles, without access to integration channels. |
|
Field: |
Permission for a WebSocket connection to work with specific WebSocket Token APIs. Specific ones can be listed, or all allowed by specifying |
Field: |
Arbitrary comment |
Field: |
Switch for synchronous script launch mode; |
Field: |
Maximum recv_svcscript execution time in seconds. 0 means the value determined by the web server is used (10 sec.). The maximum allowed value is 60 sec. |
Field: |
Channel roles for authorization through the IAM service (REST API, |
Token role mode for a channel with a user:
Not applied for a channel without a user (token roles — opts.roles). The mode change is checked by the same rule as roles: |
|
Identifier of the system user on whose behalf requests are executed. This user’s roles are also applied. Required for type= |
|
Field: |
Arbitrary title |
Field: |
Allows extending the compound with arbitrary keys and values |
Field: |
Webhook format for a |
Field: |
Object creation time |
Field: |
Time of last modification of the object |
Integration channel types
| Value | Description |
|---|---|
|
General-purpose integration channel. Applied when:
|
|
Integration channel for system event subscribers. In each integration channel, regardless of the number of connections and subscriptions, each event is sent no more than once. The recv_svcscriptcode, recv_svcscriptcode_ws, send_svcscriptcode, and send_svcscriptcode_ws fields are not used. |
|
Integration channel for messenger webhooks. Incoming messages to the web server page '/api/im/v1/:TOKEN' are forwarded to the IM account service. The channel is created by the system for an account with webhooks (identifier — account identifier, code The channel token is accepted only by the webhook page; requests with it to the REST API, The fields url, recv_svcscriptcode, recv_svcscriptcode_ws, send_svcscriptcode, send_svcscriptcode_ws, opts.userid, opts.roles, opts.filter_capabilities, opts.allow_files_api, as well as opts.roles_mode = The webhook address with the token is written by the system to the account ( |
|
Integration channel for MCP (Model Context Protocol) agents. The channel token is accepted only by the platform MCP server; direct requests with it to the REST API, The user (opts.userid) is required: rights are determined by their roles (or channel roles opts.roles), and class access restrictions (x_security) are applied. By default access is read-only (opts.allow_modify = Only the REST API (with secret masking) and the The fields url, token_remote, token_remote2, recv_svcscriptcode, recv_svcscriptcode_ws, send_svcscriptcode, and send_svcscriptcode_ws are not allowed. |
|
Determined based on the domain type. The composition of other integration channel types and service processing scripts are contained in assets by domain type. The operation is similar to the |
Integration channel token protection
The channel token (token_local) grants API access on behalf of the channel, so the platform treats it as a password. Token usage locations and protection methods are described in Integration channel tokens; secret field marking is described in Encryption and keys.
- How it is issued
-
-
The system generates the token: 12 random bytes and a checksum bound to the domain and channel (32 hexadecimal characters). A neighboring channel’s token cannot be copied into another channel: the binding is checked on creation, modification, synchronization, and import. An encrypted token is accepted only with binding
v2; a token of the old format — only asexported:when creating a channel (import of an export from a version before 1.13). -
The plaintext token is shown once — in the create and reissue response (in the administrator, the "Token shown once" window). Save it immediately; later it can only be reissued.
-
- How it is stored
-
-
In the database and domain center memory, the token is stored encrypted with the installation key (v5 format; without the key, v4 with the built-in key, see Encryption and keys). Tokens use a separate installation key subkey: ciphertexts of other secrets (settings, storages) are not accepted as a token, and an encrypted token is not decrypted by general secret decryption tools. The key is stored in the protected
:SYNC/securedirectory, inaccessible via API and scripts. -
Token lookup on requests is performed by its hash (SHA-256): there are no plaintext tokens in indexes or web server caches, and decryption is not performed when validating a request.
-
When read, exported, in the change log, and in events, the encrypted value is returned (useless and not accepted as a token without the installation key) or a mask with the fingerprint
*#<8 hex>— the first 8 characters of the token’s SHA-256 (it shows whether the token changed, but the token cannot be recovered). The plaintext token is not written to logs: microservice command lines are printed with a mask. -
For product layer microservices, the token is passed by the
%TOKENFILE%macro — a file with a random name in the working directory with permissions 0600; the microservice should read the file and delete it immediately; the system deletes it 10 seconds after startup (or by the%TOKEN%macro in the command line; the plaintext token written into the microservice command is replaced by the domain center with%TOKEN%). When the token is reissued, microservices are restarted with the new one. -
The messenger webhook address (IM account
webhookInfo.url) is stored with the plaintext token of the account channel of typeimand updated by the system when the token is reissued: theimtoken is accepted only by the IM webhook (/api/im/v1/<token>) and only allows sending webhooks to this account. To protect against forged webhooks, set provider secrets (see typeim). -
Filtering and sorting by token fields (
token_local,token_hash,token_state) are prohibited for everyone (422); channel search by token is internal only, by hash.
-
- Reissue
-
-
POST /rest/v1/service/integration_points/<id>/tokenor the "Reissue token" button in the administrator — user session only. A channel of another user or with roles the caller does not have is reissued (and modified and deleted) only by a user with theadminrole, see opts.userid. -
In bulk — POST /rest/v1/service/integration_points/token (up to 20 channels;
all— except service channels with permanent identifiers) or the "Reissue tokens" action for selected rows in the administrator — only an administrator (adminrole) via a session; new tokens are shown once as a list. -
The previous token stops working immediately (on other sites, after synchronization, up to 30 seconds), WebSocket connections using it are closed, and the channel’s HTTP subscriptions (
/api/token/v1/<token>/subscribe, webhooks) are deleted — they must be recreated. Subscriptions are also deleted when the channel is disabled (state) or deleted. External systems and settings using the token must be reconfigured. -
The previous token cannot be restored: the channel stores hashes of the last 16 previous tokens (token_revoked); saving an object read before reissue or modifying with the previous token is error 422.
-
- Previous tokens (token_revoked)
-
-
The channel stores SHA-256 hashes of the last 16 previous tokens. A hash is added on every token change: reissue, channel modification with an encrypted token (import, survival), loading a change from a site to the center.
-
The purpose is protection against restoring a previous token: an object read before reissue (form, export file, script) would return the old token when saved. Modification with a previous token (its fingerprint mask or its encrypted value) is error 422.
-
In normal reading (object, collection) the field is not returned; it is returned in export (
export=1), so it is transferred by export and survival to another system. On input (create, modify, import, load from a site), the list from the request is only added to the current one (union, SHA-256 hashes — 64 hexadecimal characters, no duplicates); entries cannot be deleted via the API — otherwise the protection could be removed by the same request that restores the old token. 16 entries are stored: the channel’s own entries are preserved, request entries occupy free slots (the request cannot displace its own entries); on token change, the previous one is added at the beginning and the oldest are displaced. Imported token validation is performed against the combined list. -
It is transferred to sites by synchronization with the center; the list is not included in the synchronization checksum, so a discrepancy between site and center lists (for example, after communication loss) is aligned on the next token change — previous token validation is performed against the list of the node accepting the change. The list also does not participate in survival comparison (export checksums) and is transferred with the channel change, see survival.
-
- Token state (token_state)
-
-
Calculated by the domain center and returned read-only:
v2— token created by the system with a random part and channel binding;legacy— old-format token, computable from the channel identifier and domain name;invalid— token of unknown origin (32 hexadecimal characters not by the formula, e.g. entered manually in old versions);unavailable— token cannot be decrypted on the server (no installation key).legacyandinvalidtokens work but are recommended for reissue. -
Visible in the administrator (channel column and card, with a warning for
legacyandinvalid), in the object REST API (GET /rest/v1/service/integration_points/<id>) and collection (GET /rest/v1/service/integration_points). Filtering and sorting by it are prohibited. More — the token_state field.
-
- Old-format tokens
-
-
Tokens created before version 1.13 are computable from the channel identifier and domain name. On update they are encrypted and continue to work, marked as
legacyin the token_state field. Reissue them. -
Tokens entered manually in old versions (32 hexadecimal characters not by the formula) continue to work and are marked as
invalid. Reissue them. -
Tokens of service channels with permanent identifiers (product layer
product_layer,service_era_meet) are reissued automatically on update. Otherwise these channels are modified on a general basis (including accepting the encrypted token of this channel).
-
- Update
-
-
Before updating, make a database backup: after the transition, tokens are stored encrypted, and rollback to the previous version without a backup is impossible.
-
Set the installation key (
erainstaller.sh keygen, then activate the configuration withgeneral.crypto_kid): without it, tokens are encrypted with the built-in key, and export returns a mask.
-
- What is not protected
-
-
Leakage of both the database and the installation key exposes tokens.
-
Change log and HistoryChanges records made before version 1.13 may contain plaintext tokens.
-
The VCS server service channel token (
service_era_meet) is passed to the VCS server in the process command line and written to the role log at startup. -
A token in a request URL (
/api/token/v1/<token>,/ws/token/v1/<token>,/api/im/v1/<token>,/api/download/v1/<token>) may end up in proxy and external system logs — use theAuthorization: Bearerheader where possible. -
Channel rights are determined by its user’s roles: a user with permission to read integration channels sees their settings. Assign users with minimally necessary roles to channels.
-