> ## Documentation Index > Fetch the complete documentation index at: https://docs.lobstersoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # Create channel > Creates a channel of the partner. A blank `remoteId` is filled with a generated placeholder. ## OpenAPI ````json POST /platform/api/partners/preview/{partnerId}/channels { "openapi": "3.1.0", "info": { "title": "Lobster Platform API", "description": "**PREVIEW:** This API is in preview and under active development. Endpoints and schemas are subject to breaking changes, and backward compatibility is not guaranteed until the API is promoted to a stable version.\n\nREST API of the Lobster Platform for headless clients. Every operation, schema and member of this document carries a description, and the create operations carry complete examples. Each tag links the page of the Lobster documentation that explains its resources.\n\n## Authentication\nFour authentication flows are available. All of them produce a bearer token that must be sent as `Authorization: Bearer ` on every request.\n\n1. **Authorization code with PKCE** (acting as a user; works with Microsoft and other SSO): the steps are in the `OAuth2AuthorizationCode` security scheme.\n2. **OAuth2 Client Credentials** (machine-to-machine): exchange a client id/secret provisioned in the Lobster administration UI at `POST /dw/register/oauth/token` with `grant_type=client_credentials&client_id=&client_secret=`.\n3. **UI Session Bearer Token**: log in via the Lobster web UI, then exchange the session cookie for a token at `GET /auth/sessionBearerToken`.\n4. **Guest User Login Token**: append a GuestUser `loginToken` as a URL query parameter (`?loginToken=`) to establish a session without a password, then retrieve the bearer token the same way.", "version": "preview" }, "servers": [ { "url": "https://platform-beta-test.lobster-cloud.com" } ], "security": [ { "OAuth2": [] }, { "OAuth2AuthorizationCode": [] }, { "SessionBearer": [] } ], "tags": [ { "name": "Channels", "description": "The channels of a partner, the concrete connections a profile uses to receive or send.", "externalDocs": { "description": "Lobster documentation", "url": "https://docs.lobstersoftware.com/docs/en/manage-partners-channels" } }, { "name": "Functions", "description": "The catalogue of mapping functions a profile's mapping can call.", "externalDocs": { "description": "Lobster documentation", "url": "https://docs.lobstersoftware.com/docs/en/functions" } }, { "name": "Partners", "description": "Integration partners, the business parties profiles exchange data with.", "externalDocs": { "description": "Lobster documentation", "url": "https://docs.lobstersoftware.com/docs/en/manage-partners" } }, { "name": "Profiles", "description": "Integration profiles: what data comes in, how it is mapped and where the result goes.", "externalDocs": { "description": "Lobster documentation", "url": "https://docs.lobstersoftware.com/docs/en/profiles" } } ], "externalDocs": { "description": "Lobster documentation", "url": "https://docs.lobstersoftware.com/docs/en/profiles" }, "paths": { "/platform/api/partners/preview/{partnerId}/channels": { "post": { "tags": [ "Channels" ], "summary": "Create channel", "description": "Creates a channel of the partner. A blank `remoteId` is filled with a generated placeholder.", "operationId": "createChannel", "parameters": [ { "name": "partnerId", "in": "path", "description": "The owning partner's `id`.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/core.IntegrationPartnerChannel", "title": "IntegrationPartnerChannel" }, "examples": { "sftp": { "summary": "SFTP", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelSFTP", "name": "acme-sftp", "active": true, "remoteId": "acme", "host": "sftp.acme.example", "port": 22, "remotePath": "./ssh/acme", "remotePassword": "PLAIN:s3cret-for-acme" } }, "http": { "summary": "HTTP", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelHTTP", "name": "acme-http", "active": true, "remoteId": "acme-http-user", "url": "https://api.acme.example/orders", "userRoles": [ "ediUser" ], "policy": "Global" } }, "as2": { "summary": "AS2", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelAS2", "name": "acme-as2", "active": true, "stationId": "LOBSTER_AS2", "partnerAs2Id": "ACME_AS2", "as2Url": "https://as2.acme.example/as2", "signingAlgorithm": "SHA256", "encryptionAlgorithm": "AES256", "mdnMode": "DEFAULT" } }, "mail": { "summary": "Mail", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelMail", "name": "acme-mail", "active": true, "remoteId": "edi@acme.example", "smtpServerUrl": "smtps://mail.acme.example:465" } }, "ftp": { "summary": "FTP", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelFTP", "name": "acme-ftp", "active": true, "host": "ftp.acme.example", "remotePassword": "PLAIN:s3cret-for-acme" } }, "oftp": { "summary": "OFTP", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelOFTP", "name": "bravo-oftp", "active": true, "localSsid": "O0013000000LOBSTER", "remoteSfid": "O0013000000BRAVO", "endpointUrl": "oftp://oftp.bravo.example:3305" } }, "cloudStorage": { "summary": "Cloud storage (S3)", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelCloudStorage", "name": "bravo-s3", "active": true, "provider": "S3", "applicationId": "AKIAEXAMPLE", "additionalParam": "eu-central-1" } }, "smb": { "summary": "SMB", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelSMB", "name": "bravo-smb", "active": true, "host": "fileserver.bravo.example", "share": "edi", "smbDomain": "BRAVO", "smbUser": "edi-svc" } }, "as4": { "summary": "AS4", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelAS4", "name": "bravo-as4", "active": true, "endpointUrl": "https://as4.bravo.example/msh" } }, "fax": { "summary": "Fax", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelFax", "name": "bravo-fax", "active": true, "isdnRemoteNumber": "+49891234567" } }, "iot": { "summary": "IoT (OPC UA)", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelIoT", "name": "bravo-iot", "active": true, "endpointUrl": "opcua://plc.bravo.example:4840", "opcSecurityPolicy": "Basic256Sha256" } }, "x400": { "summary": "X.400", "description": "A verified create body; the partner in the path owns it.", "value": { "class": "core.IntegrationPartnerChannelX400", "name": "bravo-x400", "active": true } } } } } }, "responses": { "201": { "description": "Channel created.", "headers": { "Location": { "description": "URI of the created channel.", "style": "simple", "schema": { "format": "uri" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Standard Platform API success envelope. Every response carries exactly one of `data` (success) or `error` (failure) at top level.", "properties": { "data": { "$ref": "#/components/schemas/core.IntegrationPartnerChannel", "title": "IntegrationPartnerChannel" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "schemas": { "core.IntegrationPartnerChannel": { "type": "object", "description": "One connection to a partner: the login, address and protocol a profile uses to receive from or send to it. Always addressed through its partner (`/platform/api/partners/preview/{partnerId}/channels`); the `class` names the protocol and cannot change after the create. Profiles reference a channel by its numeric `id`.\n\nSend one of these types, named in `class`:\n- `core.IntegrationPartnerChannelHTTP`: An HTTP connection with the partner, in either direction: the partner logs in to the platform's HTTP server as `remoteId` (password, OAuth and token settings are not settable through this API), and the platform calls the partner's server at `url`.\n- `core.IntegrationPartnerChannelSFTP`: An SFTP/SSH connection with the partner, in either direction: the partner logs in to the platform's SFTP server as `remoteId` and lands in `remotePath`, and the platform connects to the partner's server at `host` and `port`, checking its host key against `keyType`/`keyFingerprint` and authenticating with `privateKeyId` or a password.\n- `core.IntegrationPartnerChannelCloudStorage`: Access to a cloud storage account (Amazon S3, Azure, Google, Dropbox, OneDrive, Box).\n- `core.IntegrationPartnerChannelMail`: A mail connection with the partner: its address, the SMTP server mails are sent through, and the login settings for fetching mail by POP3/IMAP; `localCertificateId`/`remoteCertificateId` hold the S/MIME certificates.\n- `core.IntegrationPartnerChannelX400`: An X.400 connection with the partner: both sides' O/R addresses and the OSI selectors the platform's X.400 client uses toward the X.400 server.\n- `core.IntegrationPartnerChannelAS2`: An AS2 connection to the partner: the AS2 ids both sides use, the partner's AS2 URL and the signing/encryption settings for outgoing messages.\n- `core.IntegrationPartnerChannelOFTP`: An OFTP connection with the partner: both sides' OFTP identifiers, the partner's OFTP server and the certificates.\n- `core.IntegrationPartnerChannelAS4`: An AS4 connection to the partner: the partner's AS4 id, its message service endpoint and the certificates.\n- `core.IntegrationPartnerChannelAmqp10`: Broker address and credentials for an AMQP 1.0 connection (e.g.\n- `core.IntegrationPartnerChannelIoT`: An IoT (OPC UA) login: a partner device or application that connects as an OPC UA client to the platform's OPC UA server with user name `remoteId`; the password is not settable through this API.\n- `core.IntegrationPartnerChannelGooglePubSub`: Google Pub/Sub endpoint.\n- `core.IntegrationPartnerChannelSMB`: Access to a Windows (SMB) file share: the server, domain, user and password a file cron job or file response unit uses for `smb://` paths.\n- `core.IntegrationPartnerChannelFTP`: An FTP connection with the partner, in either direction: the partner logs in to the platform's FTP server as `remoteId` and lands in `remotePath`, and the platform connects to the partner's server at `host` and `port`.\n- `core.IntegrationPartnerChannelFax`: The partner's fax line, used by the platform's ISDN fax service: the number faxes to the partner are dialled at and incoming faxes are matched on, plus the station id and header sent.\n- `core.IntegrationPartnerChannelJms`: JMS provider URL and authentication mode.\n- `core.IntegrationPartnerChannelAmqp091`: Address and authentication mode for an AMQP 0.9.1 channel.", "discriminator": { "propertyName": "class" }, "oneOf": [ { "$ref": "#/components/schemas/core.IntegrationPartnerChannelHTTP", "title": "IntegrationPartnerChannelHTTP" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelSFTP", "title": "IntegrationPartnerChannelSFTP" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelCloudStorage", "title": "IntegrationPartnerChannelCloudStorage" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelMail", "title": "IntegrationPartnerChannelMail" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelX400", "title": "IntegrationPartnerChannelX400" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelAS2", "title": "IntegrationPartnerChannelAS2" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelOFTP", "title": "IntegrationPartnerChannelOFTP" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelAS4", "title": "IntegrationPartnerChannelAS4" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelAmqp10", "title": "IntegrationPartnerChannelAmqp10" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelIoT", "title": "IntegrationPartnerChannelIoT" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelGooglePubSub", "title": "IntegrationPartnerChannelGooglePubSub" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelSMB", "title": "IntegrationPartnerChannelSMB" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelFTP", "title": "IntegrationPartnerChannelFTP" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelFax", "title": "IntegrationPartnerChannelFax" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelJms", "title": "IntegrationPartnerChannelJms" }, { "$ref": "#/components/schemas/core.IntegrationPartnerChannelAmqp091", "title": "IntegrationPartnerChannelAmqp091" } ], "title": "IntegrationPartnerChannel" }, "core.IntegrationPartnerChannelHTTP": { "type": "object", "description": "An HTTP connection with the partner, in either direction: the partner logs in to the platform's HTTP server as `remoteId` (password, OAuth and token settings are not settable through this API), and the platform calls the partner's server at `url`. Referenced by `core.HttpProfileResponseUnit.channel` and `core.WebDAVProfileResponseUnit.channel` (send), `core.HttpAgentSettings.channelIds` (partners allowed to call the HTTP input agent) and `core.CronWebdavAgentSettings.comChannelId`. Channel list filter: `type=HTTP`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelHTTP", "description": "The type of this object, always `core.IntegrationPartnerChannelHTTP`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "groupName": { "type": "string", "default": "DEFAULT", "description": "Authentication realm of the partner's login: a login on the platform's HTTP server only finds this channel when the realm of the protected area being called matches." }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localCertificateId": { "type": "string", "description": "Id of one of the platform's own certificates (with private key) that this channel uses. Must reference an existing certificate.", "examples": [ "42" ], "pattern": "^\\d+$" }, "localId": { "type": "string", "description": "User name the platform authenticates with at the partner's HTTP server; its password is not settable through this API. `null` or left out keeps the stored value.", "examples": [ "lobster-edi" ] }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "openIdSettings": { "$ref": "#/components/schemas/core.OpenIdSettings", "description": "How the platform validates a bearer-token (JWT) login of the partner on its HTTP server: issuer, audience and the certificate or key endpoint the signature is checked against. Read back only when the stored settings are readable on this installation; otherwise `null`, and a write of `null` keeps them. `null` or left out keeps the stored settings; `{}` (every member empty) removes them. Writing settings drops the channel's OAuth2 tokens, as the editor does (the two are exclusive). While the channel issues JWT tokens itself, the settings hold its signing certificate: a change must keep a stored `certificateId` with a private key, must not set `certificateDynamicFetch`, and cannot remove the settings.", "title": "OpenIdSettings" }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "policy": { "type": "string", "description": "Name of the rate-limit policy applied to requests the partner sends through this HTTP channel. `Global` is built in. `null` or left out keeps the stored value; a blank string clears it.", "examples": [ "Global" ] }, "remoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) in the certificate store that this channel uses, the counterpart of `localCertificateId`. Must reference an existing certificate.", "examples": [ "43" ], "pattern": "^\\d+$" }, "remoteId": { "type": "string", "description": "User name the partner logs in with on the platform's HTTP server (HTTP authentication); its password is not settable through this API. Must be unique among all HTTP channels. Left out, the server fills an `AUTO_CREATE_...` placeholder that nobody can log in with.", "examples": [ "acme-http-user" ] }, "url": { "type": "string", "description": "Base URL of the partner's server. An HTTP response unit that names this channel takes the host (and the port, if the unit sets none) from it when its own host is empty or ``, and replaces `` in its URL with this URL's path; an HTTP cron job replaces `` with the whole URL.", "examples": [ "https://api.acme.example/orders" ], "pattern": "^https?://.+" }, "userRoles": { "type": "array", "description": "Role names the partner holds after logging in with this channel; which role a protected HTTP area requires is part of the platform's HTTP server configuration, not of the channel. Stored as given.", "items": { "type": "string" } } }, "required": [ "name" ], "title": "IntegrationPartnerChannelHTTP" }, "core.IntegrationPartnerChannelSFTP": { "type": "object", "description": "An SFTP/SSH connection with the partner, in either direction: the partner logs in to the platform's SFTP server as `remoteId` and lands in `remotePath`, and the platform connects to the partner's server at `host` and `port`, checking its host key against `keyType`/`keyFingerprint` and authenticating with `privateKeyId` or a password. Referenced by `core.CronSftpAgentSettings.channel` and `core.CronSshAgentSettings.channel` (fetch), `core.SSHProfileResponseUnit.channel` (send) and `core.SFTPAgentSettings.channels` (partners allowed to upload). The partner's login password is `remotePassword`; the platform's own password at the partner's server is not settable through this API. Channel list filter `type=SFTP`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelSFTP", "description": "The type of this object, always `core.IntegrationPartnerChannelSFTP`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "allowedProtocols": { "type": "array", "description": "Protocols the partner may log in to the platform's SSH server with: any of `SCP`, `SFTP`, `SSH` (remote command execution). At least one must stay allowed; `null`, an empty list or left out keeps the stored allowance, which on a new channel permits `SCP` and `SFTP` but not `SSH`.", "examples": [ "[\"SFTP\"]" ], "items": { "$ref": "#/components/schemas/core.SshProtocol", "title": "SshProtocol" } }, "blackListAddresses": { "type": "array", "description": "Addresses the partner may not log in to the platform's SFTP server from: IP addresses, host names or `address/netmask` ranges, e.g. `203.0.113.0/255.255.255.0`. Leaving it out keeps the stored list, `null` or an empty list removes it.", "examples": [ "[\"203.0.113.7\"]" ], "items": { "type": "string" } }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "host": { "type": "string", "description": "Host name or IP address of the partner's SFTP server - no scheme, port or path. Used when the platform connects to the partner; a host set in the cron job or response unit overrides it. `{\"host\": null, \"port\": null}` clears the address.", "examples": [ "sftp.acme.example" ], "pattern": "^(\\[[0-9A-Fa-f:.]+\\]|[^\\s/\\\\?#@:\\[\\]]+)$" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "keyFingerprint": { "type": "string", "description": "Fingerprint of the host key the partner's SFTP server must present when the platform connects; compared case-insensitively together with `keyType`, and the connection fails on a mismatch. Left blank, any host key is accepted.", "examples": [ "SHA256:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU" ] }, "keyType": { "type": "string", "description": "Type of the host key the partner's SFTP server must present, as the SSH library reports it; checked together with `keyFingerprint`.", "examples": [ "ssh-ed25519" ] }, "localId": { "type": "string", "description": "User name the platform logs in with at the partner's SFTP server (SSH login); its password is not settable through this API. `null` or left out keeps the stored value.", "examples": [ "lobster-edi" ] }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "port": { "type": "integer", "format": "int32", "default": 22, "description": "TCP port of the partner's SFTP server. Requires `host`. A port set in the cron job or response unit overrides it.", "examples": [ 22 ], "maximum": 65535, "minimum": 1 }, "privateKeyId": { "type": "string", "description": "Id of the local certificate holding the key pair the platform authenticates with (public-key authentication) when it connects to the partner's SFTP server. Must reference an existing certificate with an SSH common name.", "examples": [ "42" ], "pattern": "^\\d+$" }, "remoteCertificateIds": { "type": "array", "description": "Ids of the partner's certificates (public keys) in the certificate store, one of which the partner may authenticate with when it logs in to the platform's SFTP server by public key. Each must reference an existing certificate. Leaving it out keeps the stored list, `null` or an empty list removes it.", "examples": [ "[\"43\"]" ], "items": { "type": "string" } }, "remoteId": { "type": "string", "description": "User name the partner logs in with on the platform's SFTP server; its password is `remotePassword`, its public keys are `remoteCertificateIds`. Must be unique among all SFTP channels. Left out, the server fills an `AUTO_CREATE_...` placeholder that nobody can log in with.", "examples": [ "acme" ] }, "remotePassword": { "type": "string", "format": "password", "description": "The password the partner logs in with on the platform's server as `remoteId`. A secret: a read returns it encrypted, a write accepts that encrypted value unchanged or the cleartext as `\"PLAIN:\"`. Required on create. A channel that has one cannot be changed to an empty one; a channel stored without one stays writable without. `null` or left out keeps the stored value. Holds a secret. A read returns it encrypted; a write accepts either that encrypted form or the cleartext behind a \"PLAIN:\" prefix, and rejects anything else.", "examples": [ "PLAIN:s3cret-for-acme" ], "minLength": 1 }, "remotePath": { "type": "string", "description": "Directory on the Lobster server that becomes the partner's home when it logs in to the platform's SFTP server as `remoteId` (relative paths resolve against the server's working directory). Not a path on the partner's server. Without one the partner's file paths resolve against the server's working directory. Left out or blank on create, the server picks `ssh/` like the channel editor and creates that directory, on the DMZ too where one is configured; a directory given here is not created. A stored directory cannot be changed to a blank one (422), which an overwrite patch that leaves the member out would do.", "examples": [ "./ssh/acme" ] }, "virtualRoot": { "type": "boolean", "description": "Whether the partner, logged in on the platform's SFTP server, sees a virtual file system with its home directory as the root (`/`) instead of the real path of the home directory. `null` or left out keeps the stored value; a new channel shows the real path." }, "whiteListAddresses": { "type": "array", "description": "Addresses the partner may log in to the platform's SFTP server from: IP addresses, host names or `address/netmask` ranges, e.g. `198.51.100.0/255.255.255.0`. Leaving it out keeps the stored list, `null` or an empty list removes it; with a list set, a login from any other address is refused.", "examples": [ "[\"198.51.100.0/255.255.255.0\"]" ], "items": { "type": "string" } }, "wireCharset": { "type": "string", "description": "Character set the SFTP/SCP server and client use for file names on the wire, e.g. `ISO-8859-1`. Not validated on save. Leaving it out keeps the stored value, `null` or an empty string removes it so the SSH library's default applies.", "examples": [ "ISO-8859-1" ] } }, "required": [ "name", "remotePassword" ], "title": "IntegrationPartnerChannelSFTP" }, "core.IntegrationPartnerChannelCloudStorage": { "type": "object", "description": "Access to a cloud storage account (Amazon S3, Azure, Google, Dropbox, OneDrive, Box). Needs `provider` (fixed after create) and `applicationId`, plus `additionalParam` for `S3` and `GOOGLE_CLOUD`; no credential is settable through this API, so a channel created here is not usable until provisioned elsewhere. Referenced by `core.CloudStorageProfileResponseUnit.channel` and `core.CronCloudStorageAgentSettings.comChannelId`; channel list filter `type=CloudStorage`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelCloudStorage", "description": "The type of this object, always `core.IntegrationPartnerChannelCloudStorage`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "additionalParam": { "type": "string", "description": "Provider-specific extra value: the AWS region for `S3`, the project id for `GOOGLE_CLOUD`, the Microsoft tenant for `ONEDRIVE_M365` (filled with `common` when left out on create), the storage account for Azure with OAuth2. Required on create for `S3` and `GOOGLE_CLOUD`, and for these three providers a write may not blank it.", "examples": [ "eu-central-1" ] }, "applicationId": { "type": "string", "description": "The id the channel authenticates with at the provider - the access key id for `S3`, the Google e-mail for `GOOGLE_CLOUD`, the storage account name for Azure with shared key, the app's client id for the OAuth providers. An identifier, not a secret. Required on create; a write may not blank it. Two channels must not share the same `provider`, `applicationId` and `additionalParam` while neither has a secret yet.", "minLength": 1 }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "legacyImplementation": { "type": "boolean", "default": true, "description": "Whether the channel runs the older of the two cloud client implementations; `true` for a channel that never stored a choice. Read-only: it decides where the secret is kept.", "readOnly": true }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "oauth2Authentication": { "type": "boolean", "default": false, "description": "For `AZURE_FILE` and `AZURE_BLOB`: `true` when the channel authenticates with OAuth2 (then `tenant` and `additionalParam` apply), `false` for a shared key. Read-only.", "readOnly": true }, "oauth2RefreshUrl": { "type": "string", "description": "OAuth2 token endpoint the channel refreshes its access token at. Derived by the platform from `provider` (and the tenant) once the channel is authorised; usually empty before. Read-only.", "readOnly": true }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "provider": { "$ref": "#/components/schemas/core.CloudStorageProvider", "description": "The cloud service this channel connects to. Required on create and fixed afterwards; an explicit `null` keeps the stored provider.", "title": "CloudStorageProvider" }, "tenant": { "type": "string", "description": "Microsoft tenant (directory) id or domain, used to build the OAuth2 token URL of an `AZURE_FILE` or `AZURE_BLOB` channel that authenticates with OAuth2 instead of a shared key (see `oauth2Authentication`)." } }, "required": [ "applicationId", "name" ], "title": "IntegrationPartnerChannelCloudStorage" }, "core.IntegrationPartnerChannelMail": { "type": "object", "description": "A mail connection with the partner: its address, the SMTP server mails are sent through, and the login settings for fetching mail by POP3/IMAP; `localCertificateId`/`remoteCertificateId` hold the S/MIME certificates. Referenced by `core.CronPop3AgentSettings.channel` and `core.CronImapAgentSettings.channel` (fetch), `core.SMTPAgentSettings.channel` and `core.MailDispatchRule.channel`. The SMTP and retrieval user names and all passwords are not settable through this API; channel list filter `type=Mail`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelMail", "description": "The type of this object, always `core.IntegrationPartnerChannelMail`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "allowedProtocols": { "type": "array", "description": "What the channel may be used for: any of `SMTP` and `ASMTP` (sending mail, without and with a login) and `POP3` and `IMAP` (fetching mail). At least one must stay allowed (an empty list leaves the stored allowance unchanged), and `POP3` and `IMAP` are mutually exclusive (the editor keeps one); `null` or left out keeps the stored allowance, which on a new channel permits all four.", "examples": [ "[\"SMTP\", \"IMAP\"]" ], "items": { "$ref": "#/components/schemas/core.MailChannelProtocol", "title": "MailChannelProtocol" } }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "encryptionAlgorithm": { "type": "string", "default": "AES", "description": "Cipher for encrypting outgoing mails; used only when the channel sends encrypted. Not validated on save. `null` or left out keeps the stored value.", "examples": [ "AES" ] }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "imapFolder": { "type": "string", "default": "INBOX", "description": "IMAP folder mail is fetched from; a directory set in the IMAP cron job overrides it.", "examples": [ "INBOX/orders" ] }, "incomingMaxSize": { "type": "integer", "format": "int64", "description": "Largest incoming mail accepted on this channel, in bytes. Must be at most 1073741824 (1024 MB). `null` (or leaving it out on create) means no limit, and an unlimited channel reads back `null`.", "examples": [ 10485760 ], "minimum": 1 }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localCertificateId": { "type": "string", "description": "Id of one of the platform's own certificates (with private key) that this channel uses. Must reference an existing certificate.", "examples": [ "42" ], "pattern": "^\\d+$" }, "localId": { "type": "string", "description": "The platform's own mail address on this channel; matched case-insensitively, so an incoming mail is assigned to the channel whatever case it is addressed in, while the address is stored and read back as given. Unless the channel stores its own SMTP or retrieval user name, the platform logs in with this address, so changing it changes that login too. `null` or left out keeps the stored value.", "examples": [ "edi@lobster.example" ] }, "localTlsAuthCertificateId": { "type": "string", "description": "Id of the platform's own certificate (with private key) it presents as TLS client certificate when it connects to the partner. Must reference an existing certificate. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "42" ], "pattern": "^\\d*$" }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "receivingEncrypted": { "type": "boolean", "default": false, "description": "Whether the messages the partner sends over this channel must be encrypted. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel accepts unencrypted messages." }, "receivingSigned": { "type": "boolean", "default": false, "description": "Whether the messages the partner sends over this channel must be signed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel accepts unsigned messages." }, "remoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) in the certificate store that this channel uses, the counterpart of `localCertificateId`. Must reference an existing certificate.", "examples": [ "43" ], "pattern": "^\\d+$" }, "remoteId": { "type": "string", "description": "The partner's mail address, stored in lower case; an SMTP response unit sends to it unless the unit names its own receiver. A channel that receives mail should hold exactly one address; this API does not check. Left out, the server fills a placeholder address (`mail...@mail.org`).", "examples": [ "edi@acme.example" ] }, "remoteTlsAuthCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) it must present as TLS client certificate when it connects to the platform. Must reference an existing certificate. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "43" ], "pattern": "^\\d*$" }, "retrievalAuthMechanism": { "type": "string", "description": "SASL mechanism for the POP3/IMAP login when mail is fetched through this channel; left out, the mail library negotiates one.", "examples": [ "XOAUTH2" ] }, "retrievalServerUrl": { "type": "string", "description": "POP3/IMAP server the platform fetches mail from through this channel (`pop3://`, `pop3s://`, `pop3es://`, `imap://`, `imaps://` or `imapes://`; the `s` variants are TLS, the `es` variants STARTTLS). Another scheme is accepted as given and fails when mail is retrieved. `null` or left out keeps the stored value.", "examples": [ "imaps://mail.acme.example:993" ] }, "sendingCompressed": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are compressed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not compress." }, "sendingEncrypted": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are encrypted. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not encrypt." }, "sendingSigned": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are signed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not sign." }, "signingAlgorithm": { "type": "string", "default": "SHA256", "description": "Hash algorithm for signing outgoing mails; used only when the channel sends signed. Not validated on save. `null` or left out keeps the stored value.", "examples": [ "SHA256" ] }, "smtpAuthMechanism": { "type": "string", "description": "SASL mechanism for the SMTP login, case-insensitive; OAuth2 tokens are not settable through this API. Left out, the mail library negotiates one.", "examples": [ "PLAIN" ] }, "smtpServerUrl": { "type": "string", "description": "SMTP server that mails to this partner are sent through (`smtp://` default port 25, `smtps://` 465, `smtpes://` for STARTTLS). A host or port set in the SMTP response unit overrides it.", "examples": [ "smtps://mail.acme.example:465" ], "pattern": "^(smtp|smtps|smtpes)://.+" } }, "required": [ "name" ], "title": "IntegrationPartnerChannelMail" }, "core.IntegrationPartnerChannelX400": { "type": "object", "description": "An X.400 connection with the partner: both sides' O/R addresses and the OSI selectors the platform's X.400 client uses toward the X.400 server. Referenced by `core.CronX400AgentSettings.channel` (fetch) and `core.X400ProfileResponseUnit.channel` (send). The X.400 server address (`x400://`), the password and the other client settings are not settable through this API; channel list filter `type=X400`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelX400", "description": "The type of this object, always `core.IntegrationPartnerChannelX400`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localId": { "type": "string", "description": "The platform's own O/R address toward this partner: the sender of messages sent through this channel (unless the response unit names one), and incoming messages must be addressed to it.", "examples": [ "C=DE;A=VIAT;O=LOBSTER;S=EDI" ] }, "maximumTpduSize": { "type": "integer", "format": "int32", "default": 1024, "description": "The largest TPDU (transport data unit) in bytes the X.400 client uses. `0` restores the default; leaving it out keeps the stored value, `null` restores it too.", "minimum": 0 }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "presentationSelector": { "type": "string", "description": "Presentation selector the X.400 client addresses on the X.400 server. Left out, the client's default applies; `[empty]` sends an explicitly empty value." }, "remoteId": { "type": "string", "description": "The partner's O/R address: the receiver of messages sent through this channel (unless the response unit names one), and an incoming message is assigned to this channel by its sender address (compared in upper case). Left out, the server fills a placeholder address (`S=dummy;A=VIAT;C=DE;O=...`).", "examples": [ "C=DE;A=VIAT;O=ACME;S=EDI" ] }, "serverAddressFiltering": { "type": "boolean", "default": false, "description": "Whether the X.400 mailbox can filter the messages it hands out by address. Leaving it out keeps the stored value, `null` resets it to `false`." }, "sessionSelector": { "type": "string", "description": "Session selector the X.400 client addresses on the X.400 server. Left out, the client's default applies; `[empty]` sends an explicitly empty value." }, "transportAccessPoint": { "type": "string", "description": "Transport access point (TSAP) the X.400 client sends when connecting to the X.400 server. Left out, the client's default applies; `[empty]` sends an explicitly empty value." }, "uafiConfigDirectory": { "type": "string", "description": "Configuration directory of the legacy UAFI X.400 interface. Stored only: the editor does not show it and the built-in X.400 client does not use it." }, "uafiInDirectory": { "type": "string", "description": "Incoming directory of the legacy UAFI X.400 interface. Stored only: the editor does not show it and the built-in X.400 client does not use it." }, "uafiOutDirectory": { "type": "string", "description": "Outgoing directory of the legacy UAFI X.400 interface. Stored only: the editor does not show it and the built-in X.400 client does not use it." } }, "required": [ "name" ], "title": "IntegrationPartnerChannelX400" }, "core.IntegrationPartnerChannelAS2": { "type": "object", "description": "An AS2 connection to the partner: the AS2 ids both sides use, the partner's AS2 URL and the signing/encryption settings for outgoing messages. Needs `stationId` (`partnerAs2Id` is filled when absent); set `as2Url` and the certificates via `localCertificateId`/`remoteCertificateId`; referenced by `core.AS2ProfileResponseUnit.channel` (send) and `core.AS2AgentSettings.channels` (partners allowed to deliver). The bridge is not settable through this API; channel list filter `type=AS2`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelAS2", "description": "The type of this object, always `core.IntegrationPartnerChannelAS2`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "as2Url": { "type": "string", "description": "The partner's AS2 endpoint that outgoing messages are posted to; an AS2 response unit without its own URL uses it.", "examples": [ "https://as2.acme.example/as2" ], "pattern": "^(https?|as2)://.+" }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "encryptionAlgorithm": { "type": "string", "default": "AES256", "description": "Cipher for encrypting outgoing messages; used only when the channel sends encrypted. Not validated on save.", "examples": [ "AES256" ] }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localCertificateId": { "type": "string", "description": "Id of one of the platform's own certificates (with private key) that this channel uses. Must reference an existing certificate.", "examples": [ "42" ], "pattern": "^\\d+$" }, "localSignCertificateId": { "type": "string", "description": "Id of the platform's own certificate (with private key) that signs the messages it sends over this channel. Must reference an existing certificate. Reads as absent while the channel signs with `localCertificateId`, which is what applies when it is unset. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "42" ], "pattern": "^\\d*$" }, "localTlsAuthCertificateId": { "type": "string", "description": "Id of the platform's own certificate (with private key) it presents as TLS client certificate when it connects to the partner. Must reference an existing certificate. Reads as absent while the channel uses `localCertificateId`, which applies when it is unset. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "42" ], "pattern": "^\\d*$" }, "mdnHashAlgorithm": { "type": "string", "default": "SHA256", "description": "Hash algorithm the MDN (receipt) is signed with, e.g. `SHA256`. Not validated on save. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "SHA256" ] }, "mdnMode": { "$ref": "#/components/schemas/core.As2MdnMode", "default": "DEFAULT", "description": "Which MDN (receipt) the platform requests for outgoing messages: `DEFAULT` = the AS2 service's system setting, `SYNCHRON` = returned in the HTTP response, `ASYNCHRON` = sent later to the MDN URL. A channel stored with another code reads back without `mdnMode`, and a write that leaves it out keeps that code.", "title": "As2MdnMode" }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "partnerAs2Id": { "type": "string", "description": "The partner's AS2 id: sent as `AS2-To` on outgoing messages, and an incoming message is assigned to this channel by its `AS2-From`. Left out, the server fills an `AUTO_CREATE_...` placeholder that no partner sends.", "examples": [ "ACME_AS2" ] }, "receivingEncrypted": { "type": "boolean", "default": false, "description": "Whether the messages the partner sends over this channel must be encrypted. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel accepts unencrypted messages." }, "receivingSigned": { "type": "boolean", "default": false, "description": "Whether the messages the partner sends over this channel must be signed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel accepts unsigned messages." }, "remoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) in the certificate store that this channel uses, the counterpart of `localCertificateId`. Must reference an existing certificate.", "examples": [ "43" ], "pattern": "^\\d+$" }, "remoteSignCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) that the signature of the messages it sends over this channel is checked against. Must reference an existing certificate. Reads as absent while the channel checks against `remoteCertificateId`, which is what applies when it is unset. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "43" ], "pattern": "^\\d*$" }, "remoteTlsAuthCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) it must present as TLS client certificate when it connects to the platform. Must reference an existing certificate. Reads as absent while the channel expects `remoteCertificateId`, which applies when it is unset. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "43" ], "pattern": "^\\d*$" }, "removeSignatureSecurityFeatures": { "type": "boolean", "default": false, "description": "Whether the security settings of the message signature are removed (the editor's \"Remove security settings of signature\" switch). Leaving it out keeps the stored value, `null` resets it to `false`; a new channel keeps them." }, "sendingChunked": { "type": "boolean", "default": false, "description": "Whether outgoing messages are sent with chunked transfer encoding, split into blocks, instead of with a content length. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not chunk." }, "sendingCompressed": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are compressed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not compress." }, "sendingEncrypted": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are encrypted. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not encrypt." }, "sendingMdnUrl": { "type": "string", "description": "URL the partner sends the asynchronous MDN (receipt) to; only used with `mdnMode` `ASYNCHRON`. Must be an HTTP or HTTPS URL. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "https://lobster.example/as2/mdn" ], "pattern": "^(https?://.+)?$" }, "sendingSigned": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are signed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not sign." }, "signingAlgorithm": { "type": "string", "default": "SHA1", "description": "Hash algorithm for signing outgoing messages; used only when the channel sends signed. Not validated on save.", "examples": [ "SHA256" ] }, "stationId": { "type": "string", "description": "The platform's own AS2 id toward this partner: sent as `AS2-From` on outgoing messages and expected as `AS2-To` on incoming ones. Required on create; a write may not blank it. Together with `partnerAs2Id` it must be unique among AS2 channels.", "examples": [ "LOBSTER_AS2" ], "minLength": 1 } }, "required": [ "name", "stationId" ], "title": "IntegrationPartnerChannelAS2" }, "core.IntegrationPartnerChannelOFTP": { "type": "object", "description": "An OFTP connection with the partner: both sides' OFTP identifiers, the partner's OFTP server and the certificates. Needs `localSsid`; `remoteSfid` and `endpointUrl` are filled from defaults when absent. Referenced by `core.CronOftpAgentSettings.channel` (fetch), `core.OftpProfileResponseUnit.channel` (send) and `core.OFTPAgentSettings.channels` (partners allowed to deliver). The session passwords and additional SFIDs are not settable through this API; channel list filter `type=OFTP`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelOFTP", "description": "The type of this object, always `core.IntegrationPartnerChannelOFTP`. Required where the member it is sent in accepts several types." }, "aceEnabled": { "type": "boolean", "default": false, "description": "Whether the certificates are exchanged with this partner automatically. Leaving it out keeps the stored value, `null` resets it to `false`." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "allowedProtocols": { "type": "array", "description": "Transports the partner may use. The editor exposes TCPIP and TCPIP_TLS; ISDN is also represented for existing channels. `null`, an empty list or omission keeps the stored allowance.", "examples": [ "[\"TCPIP\", \"TCPIP_TLS\"]" ], "items": { "$ref": "#/components/schemas/core.OftpProtocol", "title": "OftpProtocol" } }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "creditCount": { "type": "integer", "format": "int32", "default": 0, "description": "The credit count of the OFTP session. `0` removes the setting; leaving it out keeps the stored value, `null` removes it too.", "minimum": 0 }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "doubleCdSendingAllowed": { "type": "boolean", "default": false, "description": "Whether the platform may send the change-direction command twice in a row. Leaving it out keeps the stored value, `null` resets it to `false`." }, "eerpSigningRequired": { "type": "boolean", "default": false, "description": "Whether the partner's end-to-end responses must be signed. Leaving it out keeps the stored value, `null` resets it to `false`." }, "encryptionAlgorithm": { "type": "string", "default": "AES256", "description": "The encryption algorithm for OFTP messages. Leaving it out keeps the stored value, `null` resets it to `AES256`.", "pattern": "^(AES256|DESede|RSA-OAEP)$" }, "endpointUrl": { "type": "string", "description": "The partner's OFTP server the platform connects to; `oftps://` uses TLS (commonly port 6619).", "examples": [ "oftp://oftp.acme.example:3305" ], "pattern": "^oftps?://.+" }, "exchangeBufferSize": { "type": "integer", "format": "int32", "default": 0, "description": "The size of the exchange buffer in bytes. `0` removes the setting; leaving it out keeps the stored value, `null` removes it too.", "minimum": 0 }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localCertificateId": { "type": "string", "description": "Id of one of the platform's own certificates (with private key) that this channel uses. Must reference an existing certificate.", "examples": [ "42" ], "pattern": "^\\d+$" }, "localSsid": { "type": "string", "description": "The platform's own OFTP identifier (SSID) toward this partner. Required on create; a write may not blank it.", "examples": [ "O0013000000LOBSTER" ], "minLength": 1 }, "maximumProtocolReleaseLevel": { "$ref": "#/components/schemas/core.OftpReleaseLevel", "default": "V2_0", "description": "The highest OFTP protocol release the platform offers. Leaving it out keeps the stored value, `null` restores the default.", "title": "OftpReleaseLevel" }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "oftp2TslName": { "type": "string", "default": "OFTP2", "description": "The name of the trusted service list the partner's certificate is checked against. An empty string restores the default; leaving it out keeps the stored value, `null` restores it too." }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "pendingLocalCertificateId": { "type": "string", "description": "Id of the platform's own certificate (with private key) that takes over as `localCertificateId` once it is activated, for a certificate exchange in preparation. Must reference an existing certificate. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "44" ], "pattern": "^\\d*$" }, "pendingRemoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) that takes over as `remoteCertificateId` once it is activated, for a certificate exchange in preparation. Must reference an existing certificate. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "45" ], "pattern": "^\\d*$" }, "receivingEncrypted": { "type": "boolean", "default": false, "description": "Whether the messages the partner sends over this channel must be encrypted. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel accepts unencrypted messages." }, "receivingSigned": { "type": "boolean", "default": false, "description": "Whether the messages the partner sends over this channel must be signed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel accepts unsigned messages." }, "remoteCertSubject": { "type": "string", "description": "The subject of the partner's certificate the platform looks for when `remoteCertificateId` names none. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "CN=oftp.acme.example" ] }, "remoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) in the certificate store that this channel uses, the counterpart of `localCertificateId`. Must reference an existing certificate.", "examples": [ "43" ], "pattern": "^\\d+$" }, "remoteSfid": { "type": "string", "description": "The partner's OFTP identifier - the SSID it presents when it connects, which assigns the session to this channel. Must be unique among OFTP channels. Left out, the server fills an `AUTO_CREATE_...` placeholder that no partner presents.", "examples": [ "O0013000000ACME" ] }, "secureAuthenticationMandatory": { "type": "boolean", "default": false, "description": "Whether the partner must authenticate securely. Leaving it out keeps the stored value, `null` resets it to `false`." }, "sendRestartDisabled": { "type": "boolean", "default": false, "description": "Whether an interrupted send is never resumed, but started again from the beginning. Leaving it out keeps the stored value, `null` resets it to `false`." }, "sendingCompressed": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are compressed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not compress." }, "sendingEncrypted": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are encrypted. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not encrypt." }, "sendingSigned": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are signed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not sign." }, "signatureAlgorithm": { "type": "string", "default": "SHA1", "description": "The signature algorithm for OFTP messages. Leaving it out keeps the stored value, `null` resets it to `SHA1`.", "pattern": "^(SHA1|SHA256|SHA512|SHA3_512)$" }, "strictSfidChecking": { "type": "boolean", "default": false, "description": "Whether the SFID of every incoming file must match one the partner is allowed to send. Leaving it out keeps the stored value, `null` resets it to `false`." }, "tlsCipherName": { "type": "string", "description": "The TLS cipher suite to use. An empty string removes the preference; leaving it out keeps the stored value, `null` resets it to the default.", "examples": [ "TLS_AES_256_GCM_SHA384" ] }, "userIncomingDirectory": { "type": "string", "description": "The directory on the platform incoming files of this partner go to. An empty string removes it; leaving it out keeps the stored value, `null` removes it too.", "examples": [ "/data/oftp/acme/in" ] }, "userOutgoingDirectory": { "type": "string", "description": "The directory on the platform outgoing files for this partner are taken from. An empty string removes it; leaving it out keeps the stored value, `null` removes it too.", "examples": [ "/data/oftp/acme/out" ] }, "x25WindowSize": { "type": "integer", "format": "int32", "default": 0, "description": "The X.25 window size. `0` removes the setting; leaving it out keeps the stored value, `null` removes it too.", "minimum": 0 } }, "required": [ "localSsid", "name" ], "title": "IntegrationPartnerChannelOFTP" }, "core.IntegrationPartnerChannelAS4": { "type": "object", "description": "An AS4 connection to the partner: the partner's AS4 id, its message service endpoint and the certificates. Referenced by `core.As4ProfileResponseUnit.channel` (send) and `core.AS4AgentSettings.channels` (partners allowed to deliver). The platform's own AS4 id, which outgoing messages are sent from, is not settable through this API; channel list filter `type=AS4`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelAS4", "description": "The type of this object, always `core.IntegrationPartnerChannelAS4`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "encryptionAlgorithm": { "type": "string", "description": "Cipher for encrypting outgoing messages; used only when the channel sends encrypted. Not validated on save. Leaving it out keeps the stored value, `null` resets it to the default, an empty string removes it.", "examples": [ "AES256" ] }, "endpointUrl": { "type": "string", "description": "The partner's AS4 message service endpoint that outgoing messages are pushed to.", "examples": [ "https://as4.acme.example/msh" ], "pattern": "^https?://.+" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localCertificateId": { "type": "string", "description": "Id of one of the platform's own certificates (with private key) that this channel uses. Must reference an existing certificate.", "examples": [ "42" ], "pattern": "^\\d+$" }, "localSignCertificateId": { "type": "string", "description": "Id of the platform's own certificate (with private key) that signs the messages it sends over this channel. Must reference an existing certificate. Reads as absent while the channel signs with `localCertificateId`, which is what applies when it is unset. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "42" ], "pattern": "^\\d*$" }, "localTlsAuthCertificateId": { "type": "string", "description": "Id of the platform's own certificate (with private key) it presents as TLS client certificate when it connects to the partner. Must reference an existing certificate. Reads as absent while the channel uses `localCertificateId`, which applies when it is unset. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "42" ], "pattern": "^\\d*$" }, "mdnMode": { "$ref": "#/components/schemas/core.As2MdnMode", "default": "DEFAULT", "description": "Which MDN (receipt) the platform requests for outgoing messages: `DEFAULT` = the AS4 service's system setting, `SYNCHRON` = returned in the HTTP response, `ASYNCHRON` = sent later to `sendingMdnUrl`. A channel stored with another code reads back without `mdnMode`, and a write that leaves it out or sends `null` keeps that code. Otherwise leaving it out keeps the stored value and `null` resets it to `DEFAULT`.", "title": "As2MdnMode" }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "receivingEncrypted": { "type": "boolean", "default": false, "description": "Whether the messages the partner sends over this channel must be encrypted. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel accepts unencrypted messages." }, "receivingSigned": { "type": "boolean", "default": false, "description": "Whether the messages the partner sends over this channel must be signed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel accepts unsigned messages." }, "remoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) in the certificate store that this channel uses, the counterpart of `localCertificateId`. Must reference an existing certificate.", "examples": [ "43" ], "pattern": "^\\d+$" }, "remoteId": { "type": "string", "description": "The partner's AS4 id, the receiver of messages sent through this channel. Left out, the server fills an `AUTO_CREATE_...` placeholder." }, "remoteSignCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) that the signature of the messages it sends over this channel is checked against. Must reference an existing certificate. Reads as absent while the channel checks against `remoteCertificateId`, which is what applies when it is unset. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "43" ], "pattern": "^\\d*$" }, "remoteTlsAuthCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) it must present as TLS client certificate when it connects to the platform. Must reference an existing certificate. Reads as absent while the channel expects `remoteCertificateId`, which applies when it is unset. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "43" ], "pattern": "^\\d*$" }, "sendingCompressed": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are compressed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not compress." }, "sendingEncrypted": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are encrypted. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not encrypt." }, "sendingMdnUrl": { "type": "string", "description": "URL the partner sends the asynchronous MDN (receipt) to; only used with `mdnMode` `ASYNCHRON`. Must be an HTTP or HTTPS URL. Leaving it out keeps the stored value, `null` or an empty string removes it.", "examples": [ "https://lobster.example/as4/mdn" ], "pattern": "^(https?://.+)?$" }, "sendingSigned": { "type": "boolean", "default": false, "description": "Whether the messages the platform sends over this channel are signed. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel does not sign." }, "signingAlgorithm": { "type": "string", "description": "Hash algorithm for signing outgoing messages; used only when the channel sends signed. Not validated on save. Leaving it out keeps the stored value, `null` resets it to the default, an empty string removes it.", "examples": [ "SHA256" ] } }, "required": [ "name" ], "title": "IntegrationPartnerChannelAS4" }, "core.IntegrationPartnerChannelAmqp10": { "type": "object", "description": "Broker address and credentials for an AMQP 1.0 connection (e.g. Azure Service Bus, RabbitMQ). The channel only holds the credentials; the connection itself is configured where it is used. Needs `endpointUrl`; `authMode` defaults to `OAUTH2`, which needs `oauth2.principal`, `oauth2.secret`, `oauth2.tokenUrl` and an `amqps://` or `wss://` endpoint - for a plain user/password broker send `\"authMode\": \"BASIC\"` with `basic.username` and `basic.password`. Unlike other channels, the secrets (`oauth2.secret`, `basic.password`) can be written here; they are never returned. Channel list filter: `type=Amqp10`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelAmqp10", "description": "The type of this object, always `core.IntegrationPartnerChannelAmqp10`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "authMode": { "type": "string", "default": "OAUTH2", "description": "How the platform authenticates at the broker: `OAUTH2` fetches a token with the `oauth2` credentials and sends it in the SASL exchange; `OAUTH2_CBS` sends that token to the broker's `$cbs` node after connecting, as Azure Service Bus requires; `BASIC` logs in with `basic.username` and `basic.password`. An explicit `null` keeps the stored mode." }, "basic": { "$ref": "#/components/schemas/core.Amqp10BasicAuthSettings", "description": "User name and password, used when `authMode` is `BASIC`. Always present on read, without the password.", "title": "Amqp10BasicAuthSettings" }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "endpointUrl": { "type": "string", "description": "Address of the AMQP 1.0 broker (default ports 5672 for `amqp://`, 5671 for `amqps://`); `ws://` and `wss://` connect over WebSocket, with path `/` when the URL has none. `amqps://` and `wss://` use TLS, which the OAuth2 modes require. Required on create; an explicit `null` keeps the stored address.", "examples": [ "amqps://mybus.servicebus.windows.net:5671" ], "pattern": "^(amqp|amqps|ws|wss)://.+" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localCertificateId": { "type": "string", "description": "Id of one of the platform's own certificates (with private key) that this channel uses. Must reference an existing certificate.", "examples": [ "42" ], "pattern": "^\\d+$" }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "oauth2": { "$ref": "#/components/schemas/core.Amqp10OAuth2Settings", "description": "OAuth2 client credentials, used when `authMode` is `OAUTH2` or `OAUTH2_CBS`. Read back only when the channel has stored credentials; `null` removes them.", "title": "Amqp10OAuth2Settings" }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "remoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) in the certificate store that this channel uses, the counterpart of `localCertificateId`. Must reference an existing certificate.", "examples": [ "43" ], "pattern": "^\\d+$" }, "remoteId": { "type": "string", "description": "Internal identity of the channel, generated by the server (an `AUTO_CREATE_...` value); it has no meaning for the broker connection and cannot be written.", "readOnly": true } }, "required": [ "name" ], "title": "IntegrationPartnerChannelAmqp10" }, "core.IntegrationPartnerChannelIoT": { "type": "object", "description": "An IoT (OPC UA) login: a partner device or application that connects as an OPC UA client to the platform's OPC UA server with user name `remoteId`; the password is not settable through this API. Referenced by `core.IoTAgentSettings.channelIds`. Channel list filter: `type=IoT`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelIoT", "description": "The type of this object, always `core.IntegrationPartnerChannelIoT`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "endpointUrl": { "type": "string", "description": "Address of the partner's endpoint. Stored on the channel; the platform's OPC UA server does not use it when the partner logs in.", "examples": [ "opcua://plc.acme.example:4840" ], "pattern": "^(https?|opcua)://.+" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localCertificateId": { "type": "string", "description": "Id of one of the platform's own certificates (with private key) that this channel uses. Must reference an existing certificate.", "examples": [ "42" ], "pattern": "^\\d+$" }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "opcSecurityPolicy": { "type": "string", "default": "None", "description": "OPC UA security policy name; reads back as `None` when unset. Stored only: neither the platform's OPC UA server nor its OPC UA client connections read it.", "examples": [ "Basic256Sha256" ], "pattern": "^(None|Basic128Rsa15|Basic256|Basic256Sha256|Aes128_Sha256_RsaOaep|Aes256_Sha256_RsaPss)$" }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "remoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) in the certificate store that this channel uses, the counterpart of `localCertificateId`. Must reference an existing certificate.", "examples": [ "43" ], "pattern": "^\\d+$" }, "remoteId": { "type": "string", "description": "User name the partner's OPC UA client logs in with on the platform's OPC UA server; only active channels are accepted, and the password is not settable through this API. Must be unique among IoT channels. Left out, the server fills an `AUTO_CREATE_...` placeholder that nobody can log in with." } }, "required": [ "name" ], "title": "IntegrationPartnerChannelIoT" }, "core.IntegrationPartnerChannelGooglePubSub": { "type": "object", "description": "Google Pub/Sub endpoint. Credential JSON is never exposed.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelGooglePubSub", "description": "The type of this object, always `core.IntegrationPartnerChannelGooglePubSub`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "endpointUrl": { "type": "string", "description": "HTTP(S) endpoint URL used by the channel.", "examples": [ "https://pubsub.googleapis.com" ], "minLength": 1, "pattern": "^https?://.+" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" } }, "required": [ "endpointUrl", "name" ], "title": "IntegrationPartnerChannelGooglePubSub" }, "core.IntegrationPartnerChannelSMB": { "type": "object", "description": "Access to a Windows (SMB) file share: the server, domain, user and password a file cron job or file response unit uses for `smb://` paths. Needs `host`, `smbDomain` and `smbUser`; a profile's file path names the server as ``, which is replaced by `host`, and the unit's own user, password and domain win over the channel's. A file cron agent links one through its `channel` member. The SMB password is not settable through this API; channel list filter `type=SMB`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelSMB", "description": "The type of this object, always `core.IntegrationPartnerChannelSMB`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "host": { "type": "string", "description": "Host name or IP address of the SMB file server - no scheme, port or path. Replaces `` in the file path of a cron job or response unit that uses this channel. Required on create; a write may not blank it.", "examples": [ "fileserver.acme.example" ], "minLength": 1, "pattern": "^(\\[[0-9A-Fa-f:.]+\\]|[^\\s/\\\\?#@:\\[\\]]+)$" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localId": { "type": "string", "description": "Identity of the channel, composed by the server as `///@` in lower case; it follows `host`, `smbUser` and `smbDomain` and cannot be written. It is the channel's uniqueness key, so a channel without `smbUser` reads `///null@` (without a domain, no `@` part) and collides with every other such channel on the same host.", "examples": [ "//fileserver/svc-edi@acme" ], "readOnly": true }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "remoteId": { "type": "string", "description": "Internal identity of the channel, generated by the server (an `AUTO_CREATE_...` value); it has no meaning for the SMB connection and cannot be written.", "readOnly": true }, "share": { "type": "string", "description": "Share name, stored as the path of the channel's `smb://` address (a leading `/` is added). Needs `host`. The file cron job and response unit take only the host from the channel, so name the share in their file path as well.", "examples": [ "edi" ] }, "smbDomain": { "type": "string", "description": "Windows domain the SMB login authenticates in; a domain set in the cron job or response unit wins. Required on create; a write may not blank it.", "examples": [ "ACME" ], "minLength": 1 }, "smbUser": { "type": "string", "description": "Account used during SMB authentication, next to `smbDomain`. Required on create; a write may not blank it. `null` or left out keeps the stored value.", "examples": [ "svc-edi" ], "minLength": 1 } }, "required": [ "host", "name", "smbDomain", "smbUser" ], "title": "IntegrationPartnerChannelSMB" }, "core.IntegrationPartnerChannelFTP": { "type": "object", "description": "An FTP connection with the partner, in either direction: the partner logs in to the platform's FTP server as `remoteId` and lands in `remotePath`, and the platform connects to the partner's server at `host` and `port`. Referenced by `core.CronFtpAgentSettings.channel` (fetch), `core.FtpProfileResponseUnit.channel` (send) and `core.FTPAgentSettings.channels` (partners allowed to upload). The partner's login password is `remotePassword`; the password the platform uses at the partner's server is not settable through this API, give it in the cron job or response unit instead. Channel list filter `type=FTP`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelFTP", "description": "The type of this object, always `core.IntegrationPartnerChannelFTP`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "allowedProtocols": { "type": "array", "description": "FTP flavours the partner may log in to the platform's FTP server with: any of `FTP`, `FTPS_EXPLICIT`, `FTPS_IMPLICIT`. At least one must stay allowed; `null`, an empty list or left out keeps the stored allowance, which on a new channel permits all three.", "examples": [ "[\"FTPS_EXPLICIT\", \"FTPS_IMPLICIT\"]" ], "items": { "$ref": "#/components/schemas/core.FtpProtocol", "title": "FtpProtocol" } }, "blackListAddresses": { "type": "array", "description": "Addresses the partner may not log in to the platform's FTP server from: IP addresses, host names or `address/netmask` ranges, e.g. `203.0.113.0/255.255.255.0`. Leaving it out keeps the stored list, `null` or an empty list removes it.", "examples": [ "[\"203.0.113.7\"]" ], "items": { "type": "string" } }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "host": { "type": "string", "description": "Host name or IP address of the partner's FTP server - no scheme, port or path. Used when the platform connects to the partner; a host set in the cron job or response unit overrides it. `{\"host\": null, \"port\": null}` clears the address.", "examples": [ "ftp.acme.example" ], "pattern": "^(\\[[0-9A-Fa-f:.]+\\]|[^\\s/\\\\?#@:\\[\\]]+)$" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localCertificateId": { "type": "string", "description": "Id of one of the platform's own certificates (with private key) that this channel uses. Must reference an existing certificate.", "examples": [ "42" ], "pattern": "^\\d+$" }, "localId": { "type": "string", "description": "User name the platform logs in with at the partner's FTP server; its password is not settable through this API. `null` or left out keeps the stored value.", "examples": [ "lobster-edi" ] }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "onlyHome": { "type": "boolean", "description": "Whether the partner, logged in on the platform's FTP server as `remoteId`, is confined to its home directory (`remotePath`) and cannot change to a directory above it. `null` or left out keeps the stored value; a new channel is not confined." }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "port": { "type": "integer", "format": "int32", "description": "TCP port of the partner's FTP server; left out, the address carries no port. Requires `host`. A port set in the cron job or response unit overrides it.", "examples": [ 21 ], "maximum": 65535, "minimum": 1 }, "remoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) in the certificate store that this channel uses, the counterpart of `localCertificateId`. Must reference an existing certificate.", "examples": [ "43" ], "pattern": "^\\d+$" }, "remoteId": { "type": "string", "description": "User name the partner logs in with on the platform's FTP server; its password is `remotePassword`. Must be unique among all FTP channels. Left out, the server fills an `AUTO_CREATE_...` placeholder that nobody can log in with.", "examples": [ "acme" ] }, "remotePassword": { "type": "string", "format": "password", "description": "The password the partner logs in with on the platform's server as `remoteId`. A secret: a read returns it encrypted, a write accepts that encrypted value unchanged or the cleartext as `\"PLAIN:\"`. Required on create. A channel that has one cannot be changed to an empty one; a channel stored without one stays writable without. `null` or left out keeps the stored value. Holds a secret. A read returns it encrypted; a write accepts either that encrypted form or the cleartext behind a \"PLAIN:\" prefix, and rejects anything else.", "examples": [ "PLAIN:s3cret-for-acme" ], "minLength": 1 }, "remotePath": { "type": "string", "description": "Directory on the Lobster server that becomes the partner's home when it logs in to the platform's FTP server as `remoteId` (relative paths resolve against the server's working directory). Not a path on the partner's server. The FTP server refuses every login to a channel without one. Left out or blank on create, the server picks `ftp/` like the channel editor and creates that directory, on the DMZ too where one is configured; a directory given here is not created. A stored directory cannot be changed to a blank one (422), which an overwrite patch that leaves the member out would do.", "examples": [ "./ftp/acme" ] }, "reuseSslSession": { "type": "boolean", "default": true, "description": "Whether the control connection's TLS session is reused for the data connections of an FTPS transfer when the platform connects to the partner; some servers refuse a data connection without it. Leaving it out keeps the stored value, `null` resets it to `true`; a new channel reuses the session." }, "virtualRoot": { "type": "boolean", "default": false, "description": "Whether the partner, logged in on the platform's FTP server, sees a virtual file system with its home directory as the root (`/`) instead of the real path of the home directory. Leaving it out keeps the stored value, `null` resets it to `false`; a new channel shows the real path." }, "whiteListAddresses": { "type": "array", "description": "Addresses the partner may log in to the platform's FTP server from: IP addresses, host names or `address/netmask` ranges, e.g. `198.51.100.0/255.255.255.0`. Leaving it out keeps the stored list, `null` or an empty list removes it; with a list set, a login from any other address is refused.", "examples": [ "[\"198.51.100.0/255.255.255.0\"]" ], "items": { "type": "string" } } }, "required": [ "name", "remotePassword" ], "title": "IntegrationPartnerChannelFTP" }, "core.IntegrationPartnerChannelFax": { "type": "object", "description": "The partner's fax line, used by the platform's ISDN fax service: the number faxes to the partner are dialled at and incoming faxes are matched on, plus the station id and header sent. Needs `isdnRemoteNumber`. Referenced by `core.FaxProfileResponseUnit.channel` (send) and `core.FaxAgentSettings.channelIds` (partners whose faxes the profile receives). Channel list filter: `type=Fax`.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelFax", "description": "The type of this object, always `core.IntegrationPartnerChannelFax`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "defaultSendHeadline": { "type": "string", "description": "Header line sent with faxes to this partner; left out, the fax service's default applies." }, "defaultSendStationID": { "type": "string", "description": "Station id sent with faxes to this partner; left out, the fax service's default applies." }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "expectedHeadline": { "type": "string", "description": "Fax header the partner is expected to send. Stored only: neither the editor nor the fax service uses it." }, "expectedStationID": { "type": "string", "description": "Station id the partner's fax machine is expected to send. Stored only, not checked when a fax arrives." }, "faxIncomingDirectory": { "type": "string", "description": "Directory on the Lobster server where faxes received from this partner are saved (created if missing). Left out, they go to the fax service's directory for unresolved faxes.", "examples": [ "./fax/acme" ] }, "faxOutgoingDirectory": { "type": "string", "description": "Directory for outgoing faxes. Stored only: neither the editor nor the fax service uses it." }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "isdnLocalNumber": { "type": "string", "description": "The platform's own fax number, sent as the calling number when faxing this partner; left out, the fax service's default number applies. For an incoming fax it is available to the profile as `VAR_FAX_LOCAL_NUMBER`." }, "isdnRemoteNumber": { "type": "string", "description": "The partner's fax number, dialled when a fax is sent through this channel. On create it also becomes `remoteId`, which incoming faxes are matched on. Required on create; a write may not blank it.", "examples": [ "+49891234567" ], "minLength": 1 }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "remoteId": { "type": "string", "description": "Identity an incoming fax is matched on: the calling number is compared with it. Set by the server from `isdnRemoteNumber` when the channel is created and kept afterwards - a later change of `isdnRemoteNumber` does not update it. Must be unique among fax channels. Read-only.", "readOnly": true } }, "required": [ "isdnRemoteNumber", "name" ], "title": "IntegrationPartnerChannelFax" }, "core.IntegrationPartnerChannelJms": { "type": "object", "description": "JMS provider URL and authentication mode. Basic credentials are not exposed.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelJms", "description": "The type of this object, always `core.IntegrationPartnerChannelJms`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "authMode": { "$ref": "#/components/schemas/core.ChannelAuthMode", "default": "BASIC", "description": "JMS authentication mode.", "title": "ChannelAuthMode" }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localCertificateId": { "type": "string", "description": "Id of one of the platform's own certificates (with private key) that this channel uses. Must reference an existing certificate.", "examples": [ "42" ], "pattern": "^\\d+$" }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "providerUrl": { "type": "string", "description": "Opaque JNDI/provider URL, including composite provider formats.", "examples": [ "tcp://broker.example:61616" ], "minLength": 1, "pattern": "^[A-Za-z][A-Za-z0-9+.-]*:.+" }, "remoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) in the certificate store that this channel uses, the counterpart of `localCertificateId`. Must reference an existing certificate.", "examples": [ "43" ], "pattern": "^\\d+$" } }, "required": [ "name", "providerUrl" ], "title": "IntegrationPartnerChannelJms" }, "core.IntegrationPartnerChannelAmqp091": { "type": "object", "description": "Address and authentication mode for an AMQP 0.9.1 channel. Basic credentials are not exposed.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerChannelAmqp091", "description": "The type of this object, always `core.IntegrationPartnerChannelAmqp091`. Required where the member it is sent in accepts several types." }, "active": { "type": "boolean", "default": false, "description": "Whether the channel is in use. Only active channels take part at runtime: logins on the platform's servers and the matching of incoming data to a partner skip inactive ones. A partner whose `status` is `INACTIVE` makes all its channels read as `false` in the channel list." }, "authMode": { "$ref": "#/components/schemas/core.ChannelAuthMode", "default": "BASIC", "description": "Broker authentication mode.", "title": "ChannelAuthMode" }, "communicationLogEnabled": { "type": "boolean", "description": "Whether the transfers over this channel are written to the communication log. `null` or left out keeps the stored value; a channel that never stored the setting reads as `true`." }, "communicationLogRetainDays": { "type": "integer", "format": "int32", "default": -1, "description": "Number of days the communication log keeps this channel's entries; `0` and up are stored, `-1` removes the setting so the communication log service's global retention applies. Only used while `communicationLogEnabled` is on. `null` or left out keeps the stored value; a channel that never stored one reads `-1`.", "minimum": -1 }, "contact": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "description": "The channel's contact person, the one the channel editor's contact section shows. Every channel created here gets exactly one: left out, an empty one. Only one channel contact is exposed; a channel that stores more than one shows the first, and a write leaves the others as they are. `null` or left out keeps the stored contact. On create its `id` is ignored; on update an `id` must be the channel's own contact id.", "title": "IntegrationPartnerContact" }, "direction": { "$ref": "#/components/schemas/core.ChannelDirection", "description": "The way data flows over the channel: `IN` (the partner sends to the platform), `OUT` (the platform sends to the partner) or `IN_AND_OUT`. Left out or `null` on create it defaults to `IN`; it cannot be set to `null` afterwards. JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB channels are always `IN_AND_OUT`: that is their default, any other value is refused, and a patch sending `null` there changes nothing. A legacy channel of these types stored with neither flag set reads `IN_AND_OUT` and has both flags set by its next write. Any other channel stored before this member existed, with no direction, reads back without it until one is written.", "title": "ChannelDirection" }, "endpointUrl": { "type": "string", "description": "Broker address. Only amqp:// and amqps:// are supported.", "examples": [ "amqps://broker.example:5671" ], "minLength": 1, "pattern": "^amqps?://.+" }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the channel, assigned by the server on create; on the channel resource a value sent in the body is ignored. Profiles reference a channel by this id, looked up with `GET /platform/api/partners/preview/{partnerId}/channels`.", "examples": [ 1042 ] }, "internalUsageOnly": { "type": "boolean", "default": false, "description": "Whether the channel stays on the platform's own server and is not synchronized to a DMZ server (the editor's \"Invisible to DMZ\" switch). `null` or left out keeps the stored value; a new channel is visible to the DMZ, except a new SMB channel, which is stored invisible unless it sends `false`. A new JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub and cloud storage channel is stored invisible to the DMZ, as the editor does; there the member reads absent, a value sent is ignored and a stored channel keeps its flag." }, "localCertificateId": { "type": "string", "description": "Id of one of the platform's own certificates (with private key) that this channel uses. Must reference an existing certificate.", "examples": [ "42" ], "pattern": "^\\d+$" }, "name": { "type": "string", "description": "Display name of the channel. Must be unique among the partner's channels of the same type.", "maxLength": 100, "minLength": 1 }, "partner": { "$ref": "#/components/schemas/core.IntegrationPartner", "description": "The partner that owns the channel, embedded on read. Set by the server from the `{partnerId}` in the request path; a value sent here is ignored, and a channel cannot move to another partner.", "readOnly": true, "title": "IntegrationPartner" }, "remoteCertificateId": { "type": "string", "description": "Id of the partner's certificate (public key) in the certificate store that this channel uses, the counterpart of `localCertificateId`. Must reference an existing certificate.", "examples": [ "43" ], "pattern": "^\\d+$" } }, "required": [ "endpointUrl", "name" ], "title": "IntegrationPartnerChannelAmqp091" }, "ErrorResponse": { "type": "object", "description": "Standard Platform API error envelope: every failed request carries a single `error` object. Every response carries exactly one of `data` (success) or `error` (failure) at top level.", "properties": { "error": { "$ref": "#/components/schemas/Error", "description": "What went wrong: branch on its `code`, show its `message`, and read `details` for one entry per failed member." } }, "required": [ "error" ] }, "core.IntegrationPartnerContact": { "type": "object", "description": "A contact person (a person to reach, not a login): a partner's contacts are held in the partner's `contacts` member, the contact of a single channel in that channel's `contact` member.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartnerContact", "description": "The type of this object, always `core.IntegrationPartnerContact`. Required where the member it is sent in accepts several types." }, "emailAddresses": { "type": "array", "description": "E-mail addresses of the contact, one entry per address; in the stored form (comma-separated, display names quoted) they must fit 250 characters.", "examples": [ "[\"erika.mustermann@acme.example\"]" ], "items": { "type": "string" } }, "fax": { "type": "string", "description": "Fax number of the contact.", "examples": [ "+49 30 1234568" ], "maxLength": 20 }, "id": { "type": "integer", "format": "int64", "description": "Id of the contact, assigned by the server. Ignored on create. On a partner update an id must be one of this partner's stored contact ids and updates that contact, left out creates a new one; on a channel update it must be the id of the channel's own contact, left out updates that contact." }, "language": { "type": "string", "description": "Language of the contact, as stored by the platform; left out or blank, none is set.", "examples": [ "de" ], "maxLength": 10 }, "name": { "type": "string", "description": "Name of the contact person.", "examples": [ "Erika Mustermann" ], "maxLength": 250 }, "note": { "type": "string", "description": "Free-text note about the contact." }, "phone": { "type": "string", "description": "Phone number of the contact.", "examples": [ "+49 30 1234567" ], "maxLength": 20 } }, "title": "IntegrationPartnerContact" }, "core.ChannelDirection": { "type": "string", "description": "The way data flows over a channel (its `direction`).\n\n- `IN`: Incoming only: the partner sends data to the platform. What a channel gets on create when it names none, except JMS, AMQP 0-9-1, AMQP 1.0, Google Pub/Sub, cloud storage and SMB.\n- `OUT`: Outgoing only: the platform sends data to the partner.\n- `IN_AND_OUT`: Both: data flows in either direction.", "enum": [ "IN", "OUT", "IN_AND_OUT" ], "title": "ChannelDirection" }, "core.OpenIdSettings": { "type": "object", "description": "How the platform validates a partner's bearer-token (JWT) login on its HTTP server, held in the `openIdSettings` member of an HTTP channel. A token is accepted for this channel only when its `iss` equals `issuer`, its `aud` contains `audience`, its signature verifies and it has not expired; the signature is checked against the stored certificate `certificateId`, or against the keys fetched from `url` when `certificateDynamicFetch` is `true`. Contains no secret. Read back only when the channel has stored settings; `\"openIdSettings\": {}` (every member empty) removes them.", "properties": { "class": { "type": "string", "const": "core.OpenIdSettings", "description": "The type of this object, always `core.OpenIdSettings`. Required where the member it is sent in accepts several types." }, "audience": { "type": "string", "description": "Audience (`aud` claim) a partner's token must contain: the token's `aud` may be this one value or a list that includes it.", "examples": [ "lobster-platform" ] }, "certificateDynamicFetch": { "type": "boolean", "default": false, "description": "`true` fetches the signing keys from `url` instead of using the stored certificate `certificateId`; `false`, `null` or left out uses the stored certificate." }, "certificateId": { "type": "string", "description": "Id of the stored (partner) certificate whose public key verifies the token signature; used when `certificateDynamicFetch` is not `true`. Must reference an existing certificate.", "examples": [ "43" ] }, "issuer": { "type": "string", "description": "Issuer (`iss` claim) a partner's token must carry; compared for an exact match.", "examples": [ "https://login.acme.example" ] }, "url": { "type": "string", "description": "JWKS endpoint of the issuer the signing keys are fetched from; used only when `certificateDynamicFetch` is `true`.", "examples": [ "https://login.acme.example/.well-known/jwks.json" ] } }, "title": "OpenIdSettings" }, "core.IntegrationPartner": { "type": "object", "description": "A business party the platform exchanges data with. The partner itself holds only its name, status and rate-limit policy; its connections (logins, addresses, identifiers) are channels, managed under `/platform/api/partners/preview/{partnerId}/channels`, which profiles reference instead of the partner. `{\"name\": \"ACME Logistics\"}` is enough to create one; deleting a partner also deletes all its channels.", "properties": { "class": { "type": "string", "const": "core.IntegrationPartner", "description": "The type of this object, always `core.IntegrationPartner`. Required where the member it is sent in accepts several types." }, "contacts": { "type": "array", "description": "Contacts of the partner (people, not logins). `null` or left out keeps the stored contacts; a list replaces them: contacts not in the list are deleted, entries with a known `id` are updated, entries without one are created. Not carried on the partner embedded in a channel body.", "items": { "$ref": "#/components/schemas/core.IntegrationPartnerContact", "title": "IntegrationPartnerContact" } }, "id": { "type": "integer", "format": "int64", "description": "Numeric id of the partner, assigned by the server on create; it is the `{partnerId}` in the partner's URLs and its channels' URLs. A value sent in a body is ignored.", "readOnly": true }, "isManagedByTpm": { "type": "boolean", "description": "`true` when the partner is managed by the connected Trading Partner Manager (TPM). Such a partner and its channels cannot be deleted through this API. Set only by the TPM synchronisation; a value sent here is ignored.", "readOnly": true }, "name": { "type": "string", "description": "Display name of the partner. Must be unique among all partners that are not deleted.", "examples": [ "ACME Logistics" ], "maxLength": 250, "minLength": 1 }, "policy": { "type": "string", "description": "Name of the rate-limit policy for requests this partner sends to the platform's REST API and MCP endpoints through its HTTP channels; it applies when the HTTP channel itself names no policy. `Global` is built in; another name must reference an existing policy. Left out on create or blank, the partner has no policy; an explicit `null` keeps the stored value.", "examples": [ "Global" ] }, "status": { "$ref": "#/components/schemas/core.PartnerStatus", "default": "ACTIVE", "description": "Whether the partner is in use. An explicit `null` keeps the stored value. `DELETED` cannot be written - delete the partner with DELETE instead.", "title": "PartnerStatus" } }, "required": [ "name" ], "title": "IntegrationPartner" }, "core.SshProtocol": { "type": "string", "description": "An SSH flavour the partner may use to log in to the platform's SFTP server: `allowedProtocols` of an SFTP channel.\n\n- `SCP`: SCP: file copy over SSH.\n- `SFTP`: SFTP: file transfer over SSH.\n- `SSH`: SSH: remote command execution. Not allowed on a new channel.", "enum": [ "SCP", "SFTP", "SSH" ], "title": "SshProtocol" }, "core.CloudStorageProvider": { "type": "string", "description": "The cloud storage service a cloud storage channel connects to (its `provider`). Required on create and fixed afterwards, since the channel's credential is stored where this provider expects it. The provider also decides what `applicationId` and `additionalParam` mean.\n\n- `DROPBOX`: Dropbox. OAuth consent is not settable through this API.\n- `S3`: Amazon S3; `applicationId` is the access key id, `additionalParam` the required AWS region. The secret access key is not settable through this API.\n- `ONEDRIVE`: Microsoft OneDrive; deprecated, prefer `ONEDRIVE_M365`.\n- `ONEDRIVE_BUSINESS`: Microsoft OneDrive Business; deprecated, prefer `ONEDRIVE_M365`.\n- `GOOGLE_DRIVE`: Google Drive. OAuth consent is not settable through this API.\n- `BOX`: Box. OAuth consent is not settable through this API.\n- `AZURE_FILE`: Microsoft Azure File Storage; with shared-key authentication (the default) `applicationId` is the storage account name. The shared key is not settable through this API.\n- `GOOGLE_CLOUD`: Google Cloud Storage; `applicationId` is the Google account e-mail of the key, `additionalParam` the required project id. The private key is not settable through this API.\n- `AZURE_BLOB`: Microsoft Azure Blob Storage; with shared-key authentication (the default) `applicationId` is the storage account name. The shared key is not settable through this API.\n- `ONEDRIVE_M365`: Microsoft 365 OneDrive / SharePoint; `additionalParam` is the Microsoft tenant, `common` when left out on create. OAuth consent is not settable through this API.", "enum": [ "DROPBOX", "S3", "ONEDRIVE", "ONEDRIVE_BUSINESS", "GOOGLE_DRIVE", "BOX", "AZURE_FILE", "GOOGLE_CLOUD", "AZURE_BLOB", "ONEDRIVE_M365" ], "title": "CloudStorageProvider" }, "core.MailChannelProtocol": { "type": "string", "description": "A mail protocol the channel may be used with: `allowedProtocols` of a mail channel.\n\n- `SMTP`: SMTP: sending mail without login.\n- `ASMTP`: ASMTP: sending mail through an SMTP server that requires a login.\n- `POP3`: POP3: fetching mail from a POP3 mailbox.\n- `IMAP`: IMAP: fetching mail from an IMAP mailbox.", "enum": [ "SMTP", "ASMTP", "POP3", "IMAP" ], "title": "MailChannelProtocol" }, "core.As2MdnMode": { "type": "string", "description": "Which MDN (receipt) an AS2 or AS4 channel requests for its outgoing messages: `mdnMode` of an AS2 or AS4 channel.\n\n- `DEFAULT`: Uses the AS2 service's system setting.\n- `SYNCHRON`: Requests the MDN returned in the HTTP response.\n- `ASYNCHRON`: Requests the MDN sent later to the channel's `sendingMdnUrl`, or the AS2 service's default if none is set.", "enum": [ "DEFAULT", "SYNCHRON", "ASYNCHRON" ], "title": "As2MdnMode" }, "core.OftpProtocol": { "type": "string", "description": "An OFTP transport allowed by `allowedProtocols` on an OFTP channel.\n\n- `ISDN`: OFTP over ISDN.\n- `TCPIP`: OFTP over TCP/IP without TLS.\n- `TCPIP_TLS`: OFTP over TCP/IP with TLS.", "enum": [ "ISDN", "TCPIP", "TCPIP_TLS" ], "title": "OftpProtocol" }, "core.OftpReleaseLevel": { "type": "string", "description": "The highest OFTP protocol release an OFTP channel offers: `maximumProtocolReleaseLevel`.\n\n- `V1_2`: OFTP 1.2.\n- `V1_3`: OFTP 1.3.\n- `V1_4`: OFTP 1.4.\n- `V2_0`: OFTP 2.0.", "enum": [ "V1_2", "V1_3", "V1_4", "V2_0" ], "title": "OftpReleaseLevel" }, "core.Amqp10BasicAuthSettings": { "type": "object", "description": "User name and password an AMQP 1.0 channel logs in to the broker with (SASL `PLAIN`) when its `authMode` is `BASIC`; held in the channel's `basic` member. Always present when a channel is read, but the password is never returned. Ignored in the OAuth2 modes.", "properties": { "class": { "type": "string", "const": "core.Amqp10BasicAuthSettings", "description": "The type of this object, always `core.Amqp10BasicAuthSettings`. Required where the member it is sent in accepts several types." }, "password": { "type": "string", "description": "Password for the broker login when `authMode` is `BASIC`. Accepted on write, never returned; leaving it out or sending `null` keeps the stored password, `\"\"` clears it. Over a plain `amqp://` or `ws://` endpoint it travels unencrypted.", "writeOnly": true }, "username": { "type": "string", "description": "User name for the broker login when `authMode` is `BASIC`. An explicit `null` keeps the stored value; `\"\"` clears it.", "examples": [ "acme-user" ] } }, "title": "Amqp10BasicAuthSettings" }, "core.Amqp10OAuth2Settings": { "type": "object", "description": "OAuth2 client credentials of an AMQP 1.0 channel, held in its `oauth2` member. When the channel's `authMode` is `OAUTH2` or `OAUTH2_CBS`, the platform fetches an access token from `tokenUrl` with `principal` and `secret` and presents it to the broker; those three are then required. Read back only when the channel has stored credentials, never with `secret`; `\"oauth2\": null` removes them.", "properties": { "class": { "type": "string", "const": "core.Amqp10OAuth2Settings", "description": "The type of this object, always `core.Amqp10OAuth2Settings`. Required where the member it is sent in accepts several types." }, "principal": { "type": "string", "description": "Client id sent to `tokenUrl` when the access token is requested. Required for the OAuth2 modes.", "examples": [ "acme-client-id" ] }, "retries": { "type": "integer", "format": "int32", "default": 0, "description": "How often a failed token request is retried. A negative value is stored as 0." }, "scope": { "type": "string", "description": "Optional `scope` parameter of the token request; left out or blank, no scope is sent.", "examples": [ "https://servicebus.azure.net/.default" ] }, "secret": { "type": "string", "description": "Client secret sent with `principal` to `tokenUrl`. Required for the OAuth2 modes. Accepted on write, never returned; leaving it out or sending `null` keeps the stored secret, `\"\"` clears it. When the stored credentials cannot be read, a write of `oauth2` without `secret` requires readable stored credentials.", "writeOnly": true }, "timeout": { "type": "integer", "format": "int32", "default": 60, "description": "Timeout of the token request in seconds. A value below 1 is stored as 1.", "examples": [ 60 ] }, "tokenUrl": { "type": "string", "description": "OAuth2 token endpoint the access token is requested from. Required for the OAuth2 modes.", "examples": [ "https://login.microsoftonline.com//oauth2/v2.0/token" ] }, "viaDmz": { "type": "boolean", "default": false, "description": "`true` sends the token request through the DMZ server instead of directly from the platform." } }, "title": "Amqp10OAuth2Settings" }, "core.FtpProtocol": { "type": "string", "description": "An FTP flavour the partner may use to log in to the platform's FTP server: `allowedProtocols` of an FTP channel.\n\n- `FTP`: Plain FTP, unencrypted.\n- `FTPS_EXPLICIT`: FTPS explicit: the connection starts plain and upgrades to TLS (AUTH TLS).\n- `FTPS_IMPLICIT`: FTPS implicit: TLS from the first byte.", "enum": [ "FTP", "FTPS_EXPLICIT", "FTPS_IMPLICIT" ], "title": "FtpProtocol" }, "core.ChannelAuthMode": { "type": "string", "description": "How a JMS or AMQP 0-9-1 channel authenticates at the broker: `authMode`.\n\n- `BASIC`: Logs in with the channel's user and password.\n- `ANONYMOUS`: Connects without credentials.", "enum": [ "BASIC", "ANONYMOUS" ], "title": "ChannelAuthMode" }, "Error": { "type": "object", "description": "The error that made the request fail.", "properties": { "code": { "type": "string", "description": "Stable machine-readable `UPPER_SNAKE` error code for programmatic handling, e.g. `PARTNER_NOT_FOUND`, `VALIDATION_FAILED` or `FORBIDDEN`. New codes may be added over time; treat an unknown code according to the HTTP status class. The HTTP status itself is carried by the status line only, never duplicated here." }, "message": { "type": "string", "description": "Human-readable, non-localized explanation. Branch on `code`, never on this text." }, "details": { "type": "array", "description": "Individual failures within the request, e.g. one entry per violated field.", "items": { "$ref": "#/components/schemas/ErrorDetail" } } }, "required": [ "code", "message" ] }, "core.PartnerStatus": { "type": "string", "description": "Lifecycle state of a partner (its `status`). It switches all of the partner's channels on or off at once, on top of each channel's own `active` flag.\n\n- `ACTIVE`: The partner is in use; each of its channels works when its own `active` is true. The default.\n- `INACTIVE`: The partner is switched off: the platform treats all its channels as inactive and the channel list shows them with `active: false`, while their stored flags stay unchanged and return with `ACTIVE`.\n- `DELETED`: Soft-deleted by DELETE. Cannot be written, and a read normally never shows a deleted partner.", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ], "title": "PartnerStatus" }, "ErrorDetail": { "type": "object", "description": "A single failure within the request.", "properties": { "code": { "type": "string", "description": "Stable machine-readable `UPPER_SNAKE` code of this individual failure, e.g. `FIELD_REQUIRED`, `FIELD_INVALID` or `VALUE_OUT_OF_RANGE`." }, "message": { "type": "string", "description": "Human-readable, non-localized explanation of this individual failure." }, "target": { "type": "string", "description": "What this failure refers to, e.g. the violated field." } }, "required": [ "code", "message" ] } }, "responses": { "BadRequest": { "description": "The request could not be understood. `BAD_REQUEST` for a body that does not decode — its `message` names the property at fault — and `VALIDATION_FAILED` with one `details` entry per offending parameter for a malformed request target (an unknown query parameter or sort key). Also `BAD_REQUEST` for a response unit naming a channel this client cannot reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } } } }, "Unauthorized": { "description": "Authentication is required or the supplied credentials are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication is required to access this resource." } } } } }, "Forbidden": { "description": "The caller lacks the permission for this operation on this resource (`FORBIDDEN`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "Access to this resource is denied." } } } } }, "NotFound": { "description": "The requested resource does not exist. The code is resource-specific, e.g. `PARTNER_NOT_FOUND`, `PROFILE_NOT_FOUND` or `CHANNEL_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "PARTNER_NOT_FOUND", "message": "Partner not found: 42" } } } } }, "Conflict": { "description": "The request collides with the current state of the resource: a name already taken by another record, a `lastModified` that no longer matches because the record changed since it was read, or a delete the record's state refuses (it is open in the Lobster UI, still referenced by other objects, or managed by the Transport Manager). A field-level collision carries one `details` entry naming it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current state of the resource.", "details": [ { "code": "FIELD_INVALID", "message": "A partner with the name 'ACME' already exists.", "target": "name" } ] } } } } }, "UnprocessableEntity": { "description": "The body decoded but breaks a rule of the resource: a required member is missing, a value is not one of the accepted values or violates its pattern, length or range, a referenced id (partner, certificate, profile) does not exist, or two members contradict each other. One `details` entry per violation: `FIELD_REQUIRED` or `FIELD_INVALID`, with `target` naming the member path and `message` the rule, including the accepted values where there is a fixed set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_FAILED", "message": "Request validation failed", "details": [ { "code": "FIELD_REQUIRED", "message": "Field 'name' must not be empty.", "target": "name" } ] } } } } }, "ServerError": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred." } } } } } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "OAuth2 client-credentials flow for machine-to-machine access.\nExchange a client id/secret at `/dw/register/oauth/token` for a bearer token, then send it\nas `Authorization: Bearer `. Client credentials are provisioned in the\nLobster administration UI.\n\nThis is the client-credentials token endpoint of the Platform API. `/oauth/token`, the\n`token_endpoint` advertised at `/.well-known/oauth-authorization-server`, serves the authorization\ncode flow of the `OAuth2AuthorizationCode` scheme.", "flows": { "clientCredentials": { "tokenUrl": "/dw/register/oauth/token", "refreshUrl": "/dw/register/oauth/token", "scopes": {} } } }, "OAuth2AuthorizationCode": { "type": "oauth2", "description": "OAuth 2.1 authorization code flow with PKCE, for acting as a signed-in user. It works with Microsoft and other single sign-on providers: the provider only confirms the user's identity to the platform, which then issues its own token.\n\n1. `POST /oauth/register` (no authentication) with the JSON body `{\"redirect_uris\": [\"\"]}` returns a `client_id`. The user's browser has to reach the redirect URI.\n2. Open `/oauth/authorize` in the user's browser with `response_type=code`, `client_id`, `redirect_uri`, `state` and a `code_challenge` with `code_challenge_method=S256`. `state` is a fresh unguessable value per request, and `code_challenge` is the S256 hash of a `code_verifier` freshly generated per request from a cryptographically secure random source (43 to 128 characters, RFC 7636). The user signs in on the platform's login page, and the browser is redirected to the redirect URI with `code` and `state`; a callback whose `state` differs from the one sent is to be rejected.\n3. The code is valid for 30 seconds. Exchange it at `POST /oauth/token`, form-encoded, with `grant_type=authorization_code`, `code`, `redirect_uri`, `code_verifier` and `client_id`.\n4. The answer carries `access_token` (valid 30 minutes), `refresh_token` (valid 48 hours) and `expires_in` **in milliseconds**. Refresh with `grant_type=refresh_token`, `refresh_token` and `client_id`.", "flows": { "authorizationCode": { "authorizationUrl": "/oauth/authorize", "tokenUrl": "/oauth/token", "refreshUrl": "/oauth/token", "scopes": {} } } }, "SessionBearer": { "type": "http", "description": "Bearer token obtained from an authenticated browser or guest-user session.\n\n**Flow 1 — UI login:** Log in via the Lobster web UI at `/`, then call\n`GET /auth/sessionBearerToken` to exchange the session cookie for a bearer token.\n\n**Flow 2 — Guest user login token:** Append a GuestUser `loginToken` as a URL\nquery parameter to the base URL to establish a password-free session:\n```\nGET ?loginToken=\n```\nThen call `GET /auth/sessionBearerToken` to obtain the bearer token.", "scheme": "bearer" } } } } ````