configuring-connections

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring Connections

配置连接

A connection is a credential and configuration object that lets Celigo communicate with an external system. Every export and import references a connection via

_connectionId

. Connections must be created before the resources that use them.

Concerns when configuring a connection:

Authentication -- choosing the right auth method (OAuth, token, basic, key-pair, certificate, etc.) and providing the correct credentials
Concurrency -- how many parallel requests Celigo can make to the target system (
```
concurrencyLevel
```
). Can be shared across connections via
```
_borrowConcurrencyFromConnectionId
```
Health monitoring -- ping configuration to verify connectivity and detect credential expiration (
```
offline
```
status)
Pre-built connectors -- HTTP connectors and trading partner connectors provide pre-configured auth, base URLs, and endpoint definitions for 550+ applications
Debug logging -- temporary debug mode to capture raw request/response data for troubleshooting
iClients -- reusable OAuth credential stores (client ID/secret, scopes, token endpoints) shared across connections. See iClients section below.

Used across flows, APIs, and tools.

连接是一个凭据和配置对象，用于让Celigo与外部系统通信。每个导出和导入操作都会通过

_connectionId

引用一个连接。必须先创建连接，再创建使用该连接的资源。

配置连接时需要关注的要点：

身份验证——选择合适的认证方式（OAuth、令牌、基础认证、密钥对、证书等）并提供正确的凭据
并发设置——Celigo可向目标系统发起的并行请求数量（
```
concurrencyLevel
```
）。可通过
```
_borrowConcurrencyFromConnectionId
```
在多个连接间共享并发数
健康监控——通过Ping配置验证连接性并检测凭据过期（
```
offline
```
状态）
预构建连接器——HTTP连接器和贸易伙伴连接器为550+应用提供预配置的认证方式、基础URL和端点定义
调试日志——临时调试模式，用于捕获原始请求/响应数据以排查问题
iClients——可复用的OAuth凭据存储（客户端ID/密钥、权限范围、令牌端点），可在多个连接间共享。详见下方的iClients章节。

连接可在流程、API和工具中通用。

Connection Types

连接类型

Target System	`type`	Schema	Notes
REST/GraphQL API (with connector)	`http`	http.yml	`formType: "assistant"` , set `_httpConnectorId`
REST/GraphQL API (manual)	`http`	http.yml	Three form types: `assistant` , `http` , `graph_ql`
NetSuite ERP	`netsuite`	netsuite.yml	Use `token-auto` for new connections
Salesforce CRM	`salesforce`	salesforce.yml	Use `packagedOAuth: true` for new connections
SQL Server, MySQL, Postgres, Oracle	`rdbms`	rdbms.yml
Snowflake, BigQuery, Redshift	`rdbms`	rdbms.yml	Check sub-type in schema
Active Directory, Databricks, DB2	`jdbc`	jdbc.yml
MongoDB/Atlas	`mongodb`	mongodb.yml
DynamoDB	`dynamodb`	dynamodb.yml
FTP/SFTP/FTPS server	`ftp`	ftp.yml	Optional PGP encryption
Amazon S3	`s3`	s3.yml
Local filesystem	`filesystem`	filesystem.yml	Requires agent via `_agentId`
AS2 EDI partner	`as2`	as2.yml
Celigo VAN (EDI hub)	`van`	van.yml
AI tool server (MCP)	`mcp`	mcp.yml
Stack-deployed connector	`wrapper`	wrapper.yml
Legacy REST (do not use)	`rest`	rest.yml	Use `http` instead

目标系统	`type`	Schema	说明
REST/GraphQL API（带连接器）	`http`	http.yml	`formType: "assistant"` ，设置 `_httpConnectorId`
REST/GraphQL API（手动配置）	`http`	http.yml	三种表单类型： `assistant` 、 `http` 、 `graph_ql`
NetSuite ERP	`netsuite`	netsuite.yml	新连接使用 `token-auto`
Salesforce CRM	`salesforce`	salesforce.yml	新连接使用 `packagedOAuth: true`
SQL Server、MySQL、Postgres、Oracle	`rdbms`	rdbms.yml
Snowflake、BigQuery、Redshift	`rdbms`	rdbms.yml	查看Schema中的子类型
Active Directory、Databricks、DB2	`jdbc`	jdbc.yml
MongoDB/Atlas	`mongodb`	mongodb.yml
DynamoDB	`dynamodb`	dynamodb.yml
FTP/SFTP/FTPS服务器	`ftp`	ftp.yml	可选PGP加密
Amazon S3	`s3`	s3.yml
本地文件系统	`filesystem`	filesystem.yml	需要通过 `_agentId` 指定代理
AS2 EDI伙伴	`as2`	as2.yml
Celigo VAN（EDI中心）	`van`	van.yml
AI工具服务器（MCP）	`mcp`	mcp.yml
堆栈部署的连接器	`wrapper`	wrapper.yml
旧版REST（请勿使用）	`rest`	rest.yml	请改用 `http`

Quick Reference

快速参考

Connection Type Decision Matrix

连接类型决策矩阵

Target system	Use type	Auth method	Read schema
Any REST/GraphQL API with a Celigo connector	`http`	Connector-defined (usually OAuth2 or token)	http.yml
Any REST/GraphQL API without a connector	`http`	Token, basic, OAuth2, custom headers	http.yml
NetSuite ERP	`netsuite`	`token-auto` (Celigo-managed TBA)	netsuite.yml
Salesforce CRM	`salesforce`	`packagedOAuth: true` (Celigo OAuth)	salesforce.yml
SQL databases (Postgres, MySQL, SQL Server, Oracle)	`rdbms`	Username/password + host/port	rdbms.yml
Snowflake / BigQuery / Redshift	`rdbms`	Key-pair or username/password	rdbms.yml
MongoDB / Atlas	`mongodb`	Connection string or host/credentials	mongodb.yml
FTP / SFTP / FTPS	`ftp`	Username/password or SSH key	ftp.yml
Amazon S3	`s3`	IAM access key or role ARN	s3.yml
MCP server	`mcp`	Varies (OAuth2 or token)	mcp.yml

Which of the two HTTP rows applies is determined by search, not preference: check for a pre-built connector first (

celigo http-connectors list

) and use the manual row only when no connector exists or it doesn't fit -- see Check for a pre-built connector and global iClient.

目标系统	使用类型	认证方式	参考Schema
带有Celigo连接器的任意REST/GraphQL API	`http`	连接器定义的方式（通常为OAuth2或令牌）	http.yml
无Celigo连接器的任意REST/GraphQL API	`http`	令牌、基础认证、OAuth2、自定义请求头	http.yml
NetSuite ERP	`netsuite`	`token-auto` （Celigo托管的TBA）	netsuite.yml
Salesforce CRM	`salesforce`	`packagedOAuth: true` （Celigo OAuth）	salesforce.yml
SQL数据库（Postgres、MySQL、SQL Server、Oracle）	`rdbms`	用户名/密码 + 主机/端口	rdbms.yml
Snowflake / BigQuery / Redshift	`rdbms`	密钥对或用户名/密码	rdbms.yml
MongoDB / Atlas	`mongodb`	连接字符串或主机/凭据	mongodb.yml
FTP / SFTP / FTPS	`ftp`	用户名/密码或SSH密钥	ftp.yml
Amazon S3	`s3`	IAM访问密钥或角色ARN	s3.yml
MCP服务器	`mcp`	多种方式（OAuth2或令牌）	mcp.yml

上述两行HTTP类型的适用场景由搜索结果决定，而非偏好：先检查是否存在预构建连接器（

celigo http-connectors list

），仅当不存在连接器或连接器不适用时才使用手动配置行——详见检查预构建连接器和全局iClient。

Minimum Required Fields

必填字段

Every connection needs at minimum:

name

type

, and the type-specific config block.

Type	Required fields
`http` (connector)	`name` , `type: "http"` , `http._httpConnectorId` , `http._httpConnectorVersionId` , connector-specific auth fields
`http` (manual)	`name` , `type: "http"` , `http.baseURI` , `http.auth.type` , auth credentials
`netsuite`	`name` , `type: "netsuite"` , `netsuite.account` , `netsuite.environment` , `netsuite.authType: "token-auto"` , `netsuite._iClientId`
`salesforce`	`name` , `type: "salesforce"` , `salesforce.sandbox` (boolean), `salesforce.packagedOAuth: true`
`rdbms`	`name` , `type: "rdbms"` , `rdbms.host` , `rdbms.port` , `rdbms.database` , `rdbms.user` , `rdbms.password`
`ftp`	`name` , `type: "ftp"` , `ftp.host` , `ftp.port` , `ftp.username` , auth (password or key)
`s3`	`name` , `type: "s3"` , `s3.region` , `s3.bucket` , IAM credentials
`mongodb`	`name` , `type: "mongodb"` , `mongodb.host` or `mongodb.connectionString`

每个连接至少需要以下字段：

name

、

type

以及对应类型的配置块。

类型	必填字段
`http` （带连接器）	`name` 、 `type: "http"` 、 `http._httpConnectorId` 、 `http._httpConnectorVersionId` 、连接器特定的认证字段
`http` （手动配置）	`name` 、 `type: "http"` 、 `http.baseURI` 、 `http.auth.type` 、认证凭据
`netsuite`	`name` 、 `type: "netsuite"` 、 `netsuite.account` 、 `netsuite.environment` 、 `netsuite.authType: "token-auto"` 、 `netsuite._iClientId`
`salesforce`	`name` 、 `type: "salesforce"` 、 `salesforce.sandbox` （布尔值）、 `salesforce.packagedOAuth: true`
`rdbms`	`name` 、 `type: "rdbms"` 、 `rdbms.host` 、 `rdbms.port` 、 `rdbms.database` 、 `rdbms.user` 、 `rdbms.password`
`ftp`	`name` 、 `type: "ftp"` 、 `ftp.host` 、 `ftp.port` 、 `ftp.username` 、认证信息（密码或密钥）
`s3`	`name` 、 `type: "s3"` 、 `s3.region` 、 `s3.bucket` 、IAM凭据
`mongodb`	`name` 、 `type: "mongodb"` 、 `mongodb.host` 或 `mongodb.connectionString`

Which Schemas to Read

参考哪些Schema

Rule: Always read the base request.yml for shared fields, then the type-specific schema for the connection type you are configuring.

规则： 始终先阅读基础的request.yml以了解共享字段，再阅读对应连接类型的特定Schema。

Schema Index

Schema索引

Connection schemas (in references/schemas/):

Base fields (all connections): request.yml
Response shape: response.yml
HTTP: http.yml
NetSuite: netsuite.yml
Salesforce: salesforce.yml
RDBMS: rdbms.yml
JDBC: jdbc.yml
MongoDB: mongodb.yml
DynamoDB: dynamodb.yml
FTP: ftp.yml
S3: s3.yml
Filesystem: filesystem.yml
AS2: as2.yml
VAN: van.yml
MCP: mcp.yml
Wrapper: wrapper.yml
REST (legacy): rest.yml
OAuth: oauth.yml
JWT: jwt.yml
SSL: ssl.yml

iClient schemas (in references/iclient-schemas/):

Base fields: request.yml
Response shape: response.yml
OAuth2 providers: oauth2.yml
NetSuite: netsuite.yml
Salesforce: salesforce.yml
eBay: ebay.yml

连接Schema（位于references/schemas/）：

基础字段（所有连接）： request.yml
响应格式： response.yml
HTTP： http.yml
NetSuite： netsuite.yml
Salesforce： salesforce.yml
RDBMS： rdbms.yml
JDBC： jdbc.yml
MongoDB： mongodb.yml
DynamoDB： dynamodb.yml
FTP： ftp.yml
S3： s3.yml
文件系统： filesystem.yml
AS2： as2.yml
VAN： van.yml
MCP： mcp.yml
Wrapper： wrapper.yml
REST（旧版）： rest.yml
OAuth： oauth.yml
JWT： jwt.yml
SSL： ssl.yml

iClient Schema（位于references/iclient-schemas/）：

基础字段： request.yml
响应格式： response.yml
OAuth2提供商： oauth2.yml
NetSuite： netsuite.yml
Salesforce： salesforce.yml
eBay： ebay.yml

Related Skills

How to Build a Connection

如何创建连接

1. Identify the target system

1. 确定目标系统

What system do you need to connect to? This determines the connection type, auth method, and configuration shape.

你需要连接到哪个系统？这将决定连接类型、认证方式和配置格式。

2. Name the connection after the system, not the operation

2. 以系统名称而非操作命名连接

Connection names should describe the system and environment -- not what a specific flow does with them. Connections are shared across exports, imports, and flows, so operation-specific names become misleading as soon as a second resource uses the same connection.

Bad (operation-specific) Good (system/environment)

Bad (operation-specific)	Good (system/environment)
`Shopify - Customer Upsert`	`Shopify - my-store`
`Microsoft Dynamics 365 Business Central - Companies Export`	`Microsoft Dynamics 365 Business Central - sandbox`
`Stripe - Invoice Fetch`	`Stripe - Production`

Shopify - Customer Upsert

Shopify - my-store

Microsoft Dynamics 365 Business Central - Companies Export

Microsoft Dynamics 365 Business Central - sandbox

Stripe - Invoice Fetch

Stripe - Production

If the account has multiple environments or instances of the same system, include the distinguishing detail (store name, environment, account ID). Otherwise just the system name is fine.

连接名称应描述系统和环境——而非特定流程的用途。连接会在导出、导入和流程间共享，因此以操作为名的连接在被第二个资源使用时会产生误导。

错误示例（以操作为名）正确示例（以系统/环境为名）

错误示例（以操作为名）	正确示例（以系统/环境为名）
`Shopify - Customer Upsert`	`Shopify - my-store`
`Microsoft Dynamics 365 Business Central - Companies Export`	`Microsoft Dynamics 365 Business Central - sandbox`
`Stripe - Invoice Fetch`	`Stripe - Production`

Shopify - Customer Upsert

Shopify - my-store

Microsoft Dynamics 365 Business Central - Companies Export

Microsoft Dynamics 365 Business Central - sandbox

Stripe - Invoice Fetch

Stripe - Production

如果账户中有同一系统的多个环境或实例，请添加区分细节（店铺名称、环境、账户ID）。否则仅使用系统名称即可。

3. Check for existing connections

3. 检查现有连接

Before creating a new connection, check what already exists in the account and marketplace:

bash

undefined

创建新连接前，先检查账户和市场中已有的连接：

bash

undefined

Search the account for existing connections by name or keyword

按名称或关键词搜索账户中的现有连接

celigo account search "<application-name>"

Show what uses a connection (exports, imports)

查看哪些资源使用了该连接（导出、导入）

celigo account dependencies connection <id>

Find offline connections used by enabled flows, orphaned connections

查找已启用流程使用的离线连接、孤立连接

celigo account lint

Search marketplace for pre-built integration templates

在市场中搜索预构建的集成模板

celigo templates marketplace

Preview a template's connection model

预览模板的连接模型

celigo templates preview <id> --model Connection

List all connections

列出所有连接

celigo connections list

Filter by type

按类型筛选

celigo connections list | grep -i "<application-name>"


The account index auto-refreshes when stale (>4 hours). Force a fresh snapshot with `celigo account snapshot`.

Reusing an existing connection avoids duplicate credentials and shares concurrency.

**When presenting connection choices to the user**, filter out connections that are `offline: true` or have `status: "offline"`. Only show online/active connections as options. If ALL matching connections are offline, mention that and let the user decide whether to proceed with an offline connection or fix connectivity first.

celigo connections list | grep -i "<application-name>"


账户索引会在过期时自动刷新（>4小时）。可使用`celigo account snapshot`强制生成新快照。

复用现有连接可避免重复凭据，并共享并发数。

**向用户展示连接选项时**，过滤掉`offline: true`或`status: "offline"`的连接。仅展示在线/活跃连接作为选项。如果所有匹配的连接均为离线，请告知用户并让其决定是继续使用离线连接还是先修复连接问题。

4. Check for a pre-built connector and global iClient

4. 检查预构建连接器和全局iClient

For HTTP connections, search for a pre-built connector before configuring manually. Configure by hand only when no connector exists for the application or the connector doesn't support the auth scheme or endpoints you need:

bash

undefined

对于HTTP连接，先搜索预构建连接器再进行手动配置。仅当应用不存在连接器或连接器不支持所需的认证方案或端点时，才手动配置：

bash

undefined

Search HTTP connectors (550+ apps: Shopify, Stripe, HubSpot, etc.)

搜索HTTP连接器（550+应用：Shopify、Stripe、HubSpot等）

celigo http-connectors list celigo http-connectors get <id> --full # see auth config, endpoints, resources

celigo http-connectors list celigo http-connectors get <id> --full # 查看认证配置、端点、资源

Search trading partner connectors (EDI, AS2, VAN)

搜索贸易伙伴连接器（EDI、AS2、VAN）

celigo tp-connectors list


If an HTTP connector exists, set `http._httpConnectorId` and `http._httpConnectorVersionId` on the connection. The connector provides auth templates, base URL, and pre-built endpoints.

**Check for a global iClient.** Many pre-built connectors ship with a **global (Celigo-managed) iClient** -- a shared OAuth app registration that handles authorization out of the box (e.g., Microsoft Business Central, Shopify, Google). When a global iClient is available:

- Use it by default. Set `http.auth.type: "oauth"` with `http.auth.oauth.useIClientFields: true` and `http._iClientId` pointing to the global iClient ID.
- Do **not** fall back to static bearer token auth (`auth.type: "token"`) just because you don't have live credentials yet. The connection should be created with the correct OAuth auth shape and saved as `offline: true`.
- Only create a custom iClient if the customer has their own app registration (e.g., their own Azure AD app, Shopify private app) or if the global iClient doesn't have the required scopes/consent for their tenant.

To find existing global iClients, check any working connection in the account that uses the same connector -- its `http._iClientId` will reference the global iClient. You can also inspect the connector's auth configuration via `http-connectors get <id> --full`.

celigo tp-connectors list


如果存在HTTP连接器，请在连接中设置`http._httpConnectorId`和`http._httpConnectorVersionId`。连接器会提供认证模板、基础URL和预构建端点。

**检查全局iClient**。许多预构建连接器附带**全局（Celigo托管）iClient**——一个共享的OAuth应用注册，可直接处理授权（例如Microsoft Business Central、Shopify、Google）。当存在全局iClient时：

- 默认使用它。设置`http.auth.type: "oauth"`，并配置`http.auth.oauth.useIClientFields: true`，同时将`http._iClientId`指向全局iClient的ID。
- 不要因为暂时没有可用凭据就退而使用静态Bearer令牌认证（`auth.type: "token"`）。连接应使用正确的OAuth认证结构创建，并保存为`offline: true`。
- 仅当客户拥有自己的应用注册（例如自己的Azure AD应用、Shopify私有应用）或全局iClient没有其租户所需的权限范围/同意时，才创建自定义iClient。

要查找现有的全局iClient，可检查账户中使用同一连接器的正常工作连接——其`http._iClientId`会引用全局iClient。也可通过`http-connectors get <id> --full`查看连接器的认证配置。

5. Choose the type, auth method, and build

5. 选择类型、认证方式并创建连接

Use the Connection Types table above to pick the

type

value and open the matching schema for available auth options and required fields.

Every connection needs at minimum:

name

type

, and the type-specific config block (

http{}

netsuite{}

ftp{}

, etc.).

Offline connections must use the correct auth shape. When creating a connection without live credentials (e.g., demo, placeholder, or pre-staging), always configure the full auth structure the connection will ultimately use -- OAuth type, iClient reference, grant type, etc. -- and save with

offline: true

. This ensures the connection can be authorized in place later without reconfiguration. Never substitute static token auth as a shortcut for an OAuth connection.

使用上方的连接类型表格选择

type

值，并打开对应的Schema查看可用的认证选项和必填字段。

每个连接至少需要：

name

、

type

以及对应类型的配置块（

http{}

、

netsuite{}

、

ftp{}

等）。

离线连接必须使用正确的认证结构。当创建没有可用凭据的连接时（例如演示、占位符或预 staging），始终配置连接最终将使用的完整认证结构——OAuth类型、iClient引用、授权类型等——并以

offline: true

保存。这确保连接后续可直接授权，无需重新配置。切勿用静态令牌认证作为OAuth连接的捷径。

6. Test the connection

6. 测试连接

bash

celigo connections ping <id>

For OAuth connections, authorize via browser first:

celigo connections authorize <id>

bash

celigo connections ping <id>

对于OAuth连接，需先通过浏览器授权：

celigo connections authorize <id>

。

CLI Commands

CLI命令

bash

undefined

bash

undefined

CRUD

CRUD操作

celigo connections list celigo connections get <id> celigo connections create < connection.json celigo connections update <id> < connection.json celigo connections delete <id>

Test connectivity

测试连接性

celigo connections ping <id>

OAuth authorization (opens browser for OAuth flow)

OAuth授权（打开浏览器进行OAuth流程）

celigo connections authorize <id> [--timeout <seconds>] [--print-url]

Debug

调试

celigo connections enable-debug <id> [--duration <minutes>] celigo connections disable-debug <id> celigo connections debug-logs <id>

Integration-level connection management

集成级连接管理

celigo integrations register-connections <integrationId> <connectionIds...> celigo integrations deregister-connections <integrationId> <connectionIds...>

Replace connection across a flow's exports/imports

在流程的导出/导入中替换连接

celigo flows replace-connection <flowId> <oldConnectionId> <newConnectionId>


Note: `connections set` and `iclients set` only apply PATCH-whitelisted fields (e.g. `name`, `debugDate`, `debugUntil`; iclients also `oauth2.failPath`). PATCH never re-sends the masked credentials GET returns as `"******"`, so it's safe. Any non-whitelisted field errors instead of falling back to a full PUT that would overwrite stored secrets -- use `update` (which guards against submitting masked values) for those.

<!-- TIER:3 -->

celigo flows replace-connection <flowId> <oldConnectionId> <newConnectionId>


注意：`connections set`和`iclients set`仅应用PATCH白名单字段（例如`name`、`debugDate`、`debugUntil`；iClient还包括`oauth2.failPath`）。PATCH操作绝不会重新发送GET返回的掩码凭据`"******"`，因此是安全的。任何非白名单字段会触发错误，而非回退到会覆盖存储密钥的完整PUT操作——此类字段请使用`update`（可防止提交掩码值）。

<!-- TIER:3 -->

Pre-Submit Checklist

提交前检查清单

Before creating or updating a connection, verify:

```
name
```
describes the system/environment, not a specific operation (e.g., "Shopify - my-store", not "Shopify - Customer Upsert")
```
type
```
matches the target system (see Connection Types)
Type-specific config block is present (
```
http{}
```
,
```
netsuite{}
```
,
```
rdbms{}
```
, etc.)
Auth credentials are real values, not masked
```
"******"
```
from a prior GET
For HTTP: a pre-built connector search was done (
```
celigo http-connectors list
```
); manual config only because none exists or it doesn't fit

For HTTP connectors:

http._httpConnectorId

and

http._httpConnectorVersionId

are set

For OAuth connections: uses global iClient if connector provides one; custom iClient only when needed
For OAuth connections:
```
auth.type
```
is
```
"oauth"
```
(not
```
"token"
```
with a static bearer), even if saving
```
offline: true
```
For NetSuite:
```
netsuite.authType
```
is
```
token-auto
```
(not deprecated
```
basic
```
)
For RDBMS: host, port, database, user, and password are all provided

创建或更新连接前，请验证：

```
name
```
描述的是系统/环境，而非特定操作（例如"Shopify - my-store"，而非"Shopify - Customer Upsert"）
```
type
```
与目标系统匹配（参见连接类型）
存在对应类型的配置块（
```
http{}
```
、
```
netsuite{}
```
、
```
rdbms{}
```
等）
认证凭据是真实值，而非之前GET返回的掩码
```
"******"
```
对于HTTP连接：已搜索预构建连接器（
```
celigo http-connectors list
```
）；仅在不存在连接器或连接器不适用时才手动配置

对于HTTP连接器：已设置

http._httpConnectorId

和

http._httpConnectorVersionId

对于OAuth连接：如果连接器提供全局iClient则使用它；仅在需要时才创建自定义iClient
对于OAuth连接：
```
auth.type
```
为
```
"oauth"
```
（而非使用静态Bearer令牌的
```
"token"
```
），即使保存为
```
offline: true
```
对于NetSuite：
```
netsuite.authType
```
为
```
token-auto
```
（而非已弃用的
```
basic
```
）
对于RDBMS：已提供主机、端口、数据库、用户名和密码

Gotchas

注意事项

These apply to both connections and iClients unless noted:

GET masks credentials. Passwords, tokens, and secrets are returned as
```
"******"
```
. Never round-trip a GET response back to PUT without restoring the real values. This is why
```
set
```
only PATCHes whitelisted non-credential fields, and
```
update
```
refuses a payload still containing
```
"******"
```
unless you pass
```
--force
```
.
PUT erases omitted fields. Always GET first, modify, then PUT the complete object.
OAuth connections need browser authorization after creation. Creating via API sets up the shell, but tokens come from a browser redirect. Use
```
celigo connections authorize <id>
```
.

Connections only:

rest
type is legacy. Always use
```
type: "http"
```
for new REST connections.
NetSuite
basic
auth is deprecated. Use
```
token-auto
```
(Celigo-managed TBA) for new connections.
Debug logs are connection-scoped. Enabling debug captures request/response data for all flows using that connection.

_borrowConcurrencyFromConnectionId
shares slots. The borrowing connection's

concurrencyLevel

is ignored.

Name connections after the system, not the operation. Connections are shared across resources. "Shopify - my-store" is correct; "Shopify - Customer Upsert" is not.
Use the global iClient for OAuth connectors. When a pre-built connector ships with a global iClient, use it with
```
auth.type: "oauth"
```
-- do not substitute
```
auth.type: "token"
```
with a static bearer token, even for offline/dummy connections. Static tokens expire and produce the wrong auth shape.

以下内容适用于连接和iClient，除非另有说明：

GET操作会掩码凭据。密码、令牌和密钥会以
```
"******"
```
返回。切勿将GET响应直接回传给PUT操作，除非恢复真实值。这就是
```
set
```
仅PATCH白名单非凭据字段，而
```
update
```
会拒绝仍包含
```
"******"
```
的负载（除非传递
```
--force
```
）的原因。
PUT操作会删除遗漏字段。始终先GET，修改后再PUT完整对象。
OAuth连接创建后需要浏览器授权。通过API创建仅设置了框架，令牌需通过浏览器重定向获取。使用
```
celigo connections authorize <id>
```
。

仅适用于连接的注意事项：

rest
类型已废弃。新的REST连接请始终使用
```
type: "http"
```
。
NetSuite的
basic
认证已废弃。新连接请使用
```
token-auto
```
（Celigo托管的TBA）。
调试日志是连接级别的。启用调试会捕获所有使用该连接的流程的请求/响应数据。
_borrowConcurrencyFromConnectionId
会共享并发槽位。借用连接的
```
concurrencyLevel
```
会被忽略。
以系统而非操作命名连接。连接会在资源间共享。"Shopify - my-store"是正确的；"Shopify - Customer Upsert"则不正确。
OAuth连接器使用全局iClient。当预构建连接器附带全局iClient时，请使用
```
auth.type: "oauth"
```
——即使是离线/虚拟连接，也不要替换为使用静态Bearer令牌的
```
auth.type: "token"
```
。静态令牌会过期，并产生错误的认证结构。

Common Errors

常见错误

Error	Cause	Fix
`401 Unauthorized`	Invalid or expired credentials	Verify auth credentials; for OAuth, re-run `celigo connections authorize <id>`
`403 Forbidden`	Valid credentials but insufficient permissions	Check the user/role permissions in the target system
`422 Unprocessable Entity` -- invalid type	`type` value is not recognized or misspelled	Use exact values from Connection Types: `http` , `netsuite` , `salesforce` , `rdbms` , etc.
`422 Unprocessable Entity` -- missing fields	Required type-specific fields are absent	Check Minimum Required Fields for the connection type
`ping` returns `offline`	Connection created but cannot reach the target	Verify host/URL, credentials, firewall rules, and VPN/agent requirements
`ECONNREFUSED` / `ETIMEDOUT`	Network-level failure to target system	Check host/port, DNS resolution, firewall rules; for on-prem systems, verify `_agentId` is set
OAuth `invalid_grant`	Refresh token expired or revoked	Re-authorize: `celigo connections authorize <id>`
`"******"` saved as credential	Round-tripped a GET response back to PUT	Never PUT masked values; always provide real credentials on update
`429 Too Many Requests`	Destination rate limit exceeded	If auto-recover is enabled, the connection throttles and retries automatically; otherwise enable it or lower `concurrencyLevel` . See Credential Discipline & Runtime Behavior

错误	原因	修复方法
`401 Unauthorized`	凭据无效或过期	验证认证凭据；对于OAuth连接，重新运行 `celigo connections authorize <id>`
`403 Forbidden`	凭据有效但权限不足	检查目标系统中的用户/角色权限
`422 Unprocessable Entity` -- 无效类型	`type` 值未被识别或拼写错误	使用连接类型中的准确值： `http` 、 `netsuite` 、 `salesforce` 、 `rdbms` 等
`422 Unprocessable Entity` -- 缺少字段	缺少对应类型的必填字段	检查该连接类型的必填字段
`ping` 返回 `offline`	连接已创建但无法访问目标系统	验证主机/URL、凭据、防火墙规则以及VPN/代理要求
`ECONNREFUSED` / `ETIMEDOUT`	无法通过网络访问目标系统	检查主机/端口、DNS解析、防火墙规则；对于本地系统，验证已设置 `_agentId`
OAuth `invalid_grant`	刷新令牌过期或被撤销	重新授权： `celigo connections authorize <id>`
`"******"` 被保存为凭据	将GET响应直接回传给PUT操作	切勿PUT掩码值；更新时始终提供真实凭据
`429 Too Many Requests`	超过目标系统的速率限制	如果启用了自动恢复，连接会自动限流并重试；否则启用自动恢复或降低 `concurrencyLevel` 。详见凭据规范与运行时行为

Credential Discipline & Runtime Behavior

凭据规范与运行时行为

How connections behave once they exist -- the credential rules every update must follow, and the runtime model (state, queues, rate-limit recovery, debug) to reason about when troubleshooting.

连接创建后的行为——每次更新必须遵循的凭据规则，以及排查问题时需了解的运行时模型（状态、队列、速率限制恢复、调试）。

Never accept or echo real credentials in chat

切勿在聊天中接收或回显真实凭据

Celigo requires the external system's credentials to be re-submitted on every connection update -- a security guardrail proving the person making the change controls the target system, not a UI quirk. Because chat conversations are logged in clear text, never accept, request, or echo a real credential (API key, OAuth token or client secret, SFTP password, cert key, AS2 cert pair) in chat.

When updating a connection programmatically, send the credential fields as dummy/placeholder values so the non-credential changes the user asked for (rename, URL, concurrency) save normally. Then tell the user to finish the change by re-entering their real credentials in the Celigo UI. Signal this on every update, including trivial ones (renames, description tweaks) -- the user shouldn't have to remember which updates need a manual follow-up.
If a user pastes a real credential, treat it as compromised, full stop. The only correct mitigation: (1) rotate the credential at the external system itself -- regenerate the API key, reset the OAuth grant, rotate the SFTP password, revoke and reissue the cert pair -- then (2) update the connection in the Celigo UI with the rotated value. This holds no matter how trivial the credential looks (a sandbox key, a stale password, a client secret the user thinks is unused).

The credentials live on the durable connection record; the runtime auth state (token still valid, cert still trusted, system reachable) is separate and ephemeral.

Celigo要求在每次连接更新时重新提交外部系统的凭据——这是一项安全防护措施，用于证明进行更改的人控制着目标系统，而非UI缺陷。由于聊天记录是明文存储的，切勿在聊天中接收、请求或回显真实凭据（API密钥、OAuth令牌或客户端密钥、SFTP密码、证书密钥、AS2证书对）。

以编程方式更新连接时，将凭据字段设置为虚拟/占位值，以便用户要求的非凭据更改（重命名、URL、并发数）正常保存。然后告知用户需在Celigo UI中重新输入真实凭据以完成更改。每次更新都需提示，包括微小更改（重命名、描述调整）——用户无需记住哪些更新需要手动跟进。
如果用户粘贴了真实凭据，立即视为已泄露。唯一正确的缓解措施：(1) 在外部系统本身轮换凭据——重新生成API密钥、重置OAuth授权、轮换SFTP密码、吊销并重新颁发证书对——然后(2) 在Celigo UI中使用轮换后的值更新连接。无论凭据看起来多么无关紧要（沙箱密钥、过期密码、用户认为未使用的客户端密钥），都必须执行此操作。

凭据存储在持久化的连接记录中；运行时认证状态（令牌是否有效、证书是否受信任、系统是否可达）是独立且临时的。

Online / offline -- fix the shared connection, not each flow

在线/离线——修复共享连接，而非单个流程

A connection is online (credentials valid, target reachable, every dependent can run) or offline (token expired, API changed, network unreachable, credentials rotated without updating Celigo, cert expired). The connection resource exists in either state -- going offline doesn't delete it. Probe it with

celigo connections ping <id>

When a user reports "my flow is failing" and the root cause is the connection, fix the shared connection, not each dependent flow. One connection backs many consumers (flows, APIs, Tools, AI agents); every dependent recovers the moment the connection is back online. That one-fix-all-recover payoff is the whole point of the connection abstraction.

连接要么在线（凭据有效、目标可达、所有依赖项均可运行），要么离线（令牌过期、API变更、网络不可达、凭据已轮换但未更新Celigo、证书过期）。连接资源在两种状态下均存在——离线不会删除连接。可使用

celigo connections ping <id>

探测连接状态。

当用户报告“我的流程失败”且根本原因是连接问题时，修复共享连接，而非每个依赖流程。一个连接支持多个消费者（流程、API、工具、AI代理）；连接恢复在线后，所有依赖项都会自动恢复。这种“一次修复，全部恢复”的效果正是连接抽象的核心价值。

Connections as concurrency queues -- throughput and governance

连接作为并发队列——吞吐量与治理

Every connection is backed by its own dedicated FIFO queue. Records routed through a connection land in its queue and process first-in, first-out. Two flows using the same connection share one queue; a flow that touches multiple connections lands in multiple queues (one per connection). This is the mental model for throughput, rate limits, and "why are my flows competing for capacity?"

concurrencyLevel

sets how many messages from the queue process in parallel -- match it to the external system's published API governance limit (if the destination permits 25 parallel requests, set

concurrencyLevel: 25

to run at the ceiling without going over). Queue depth is connection-level, owned collectively by every consumer -- never attribute a deep queue to a single flow, and treat a deep queue as an explanation (work ahead in line), not a defect.

Throughput symptoms almost always point back to the connection, not the flow:

Symptom	Likely cause / fix
Flow hitting rate limits	`concurrencyLevel` too high for what the destination permits, or auto-recover disabled
Flow slow / not keeping up	`concurrencyLevel` too low; the system permits more parallelism than the connection uses
Some flows starve others	High-volume flows share one connection's queue -- partition into separate connections (high-priority vs back-office) and set concurrency per priority
Need to throttle a system	Lower `concurrencyLevel` on the connection serving it

每个连接都有自己的专用FIFO队列。通过连接路由的记录会进入该队列，并按先进先出的顺序处理。两个使用同一连接的流程共享一个队列；涉及多个连接的流程会进入多个队列（每个连接一个）。这是理解吞吐量、速率限制以及“为什么我的流程在竞争资源？”的核心模型。

concurrencyLevel

设置队列中可并行处理的消息数量——请将其匹配到外部系统公布的API治理限制（如果目标系统允许25个并行请求，设置

concurrencyLevel: 25

以在不超限的情况下达到上限）。队列深度是连接级别的，由所有消费者共同拥有——切勿将深度队列归因于单个流程，而应将其视为一种解释（有工作在排队），而非缺陷。

吞吐量问题几乎总是指向连接，而非流程：

症状	可能原因/修复方法
流程触发速率限制	`concurrencyLevel` 高于目标系统允许的值，或未启用自动恢复
流程缓慢/无法跟上进度	`concurrencyLevel` 过低；系统允许的并行度高于连接当前使用的水平
某些流程被饿死	高流量流程共享一个连接的队列——将其划分为单独的连接（高优先级 vs 后台办公）并按优先级设置并发数
需要限流某个系统	降低服务该系统的连接的 `concurrencyLevel`

Auto-recover rate-limit errors

自动恢复速率限制错误

New connections enable auto-recover rate limit errors by default, with a per-adaptor target concurrency (HTTP default 25, FTP default 1, tunable per connection). On a rate-limit error (429 or equivalent), instead of piling errors into Open errors the connection throttles itself and recovers:

Drop effective concurrency to 1 and wait ~1 minute before retrying the errored record.
Each further rate-limit error doubles the wait (2, 4, 8, ... up to 1024 minutes) -- up to eleven attempts at concurrency 1, roughly 34 hours of accumulated backoff.
On a successful retry, walk concurrency back up toward the target (1 -> 2 -> 4 -> 8 -> ...). A rate-limit error mid-recovery restarts the dance from concurrency 1.
If the full sequence still hits rate-limit errors, the platform auto-disables the setting on the connection -- it must be re-enabled manually, and until then rate-limit errors flow into Open errors like any other failure.

Recovered records land in the Resolved errors tab (not Open errors), and the concurrency adjustments appear in the connection's audit log. Mid-run, disabling auto-recover cancels recovery (the flow continues at the target concurrency; unresolved rate-limit errors go to Open errors), and changing the target concurrency takes effect immediately for subsequent retries.

新连接默认启用自动恢复速率限制错误，每个适配器有目标并发数（HTTP默认25，FTP默认1，可按连接调整）。遇到速率限制错误（429或等效错误）时，连接不会将错误堆积到未处理错误中，而是自动限流并恢复：

将有效并发数降至1，等待约1分钟后重试出错的记录。
每次后续速率限制错误会加倍等待时间（2、4、8……最多1024分钟）——最多以并发数1重试11次，累计退避时间约34小时。
重试成功后，将并发数逐步恢复到目标值（1 -> 2 -> 4 -> 8 -> ……）。恢复过程中遇到速率限制错误会重新从并发数1开始。
如果整个序列仍触发速率限制错误，平台会自动禁用该连接的此设置——必须手动重新启用，否则速率限制错误会像其他失败一样流入未处理错误。

恢复的记录会进入已解决错误标签页（而非未处理错误），并发数调整会显示在连接的审计日志中。运行中禁用自动恢复会取消恢复（流程会以目标并发数继续；未解决的速率限制错误会进入未处理错误），更改目标并发数会立即对后续重试生效。

Borrowing concurrency

借用并发数

When multiple connections point at the same system but the system enforces an account-wide rate limit, have them share one budget: set

_borrowConcurrencyFromConnectionId

on each borrowing connection to point at a parent, and set

concurrencyLevel

on the parent to the system's limit. All borrowers draw from that shared budget (a borrower's own

concurrencyLevel

is ignored). This fits the "partition by identity" pattern -- different credentials or teams, one global API limit. A borrowing connection has no auto-recover toggle of its own; the parent connection's auto-recover setting governs.

当多个连接指向同一系统但系统强制执行账户级速率限制时，可让它们共享一个预算：在每个借用连接上设置

_borrowConcurrencyFromConnectionId

指向父连接，并将父连接的

concurrencyLevel

设置为系统的限制值。所有借用连接都会从该共享预算中获取并发数（借用连接自身的

concurrencyLevel

会被忽略）。这符合“按身份分区”的模式——不同凭据或团队，共享一个全局API限制。借用连接没有自己的自动恢复开关；父连接的自动恢复设置会起作用。

Wire-level debug logging

有线级调试日志

When a flow fails in ways online/offline doesn't explain -- the target is reachable and credentials look fine, but records are rejected with cryptic errors or the wrong data comes back -- capture the raw traffic with the connection debugger:

bash

celigo connections enable-debug <id> [--duration <minutes>]   # 15 min default, up to ~1 hour
celigo connections debug-logs <id>
celigo connections disable-debug <id>

Captures every request/response through the connection with sensitive fields masked. Each entry carries an ISO date, a UUID pairing a request to its response, the resource type and id using the connection, and the request or response body (match a request to its response by shared UUID).
Logs appear only once data is actually moving -- not for flows queued but not yet processing. Captured logs remain available for 24 hours (or until cleared).
Debug is connection-scoped -- it captures traffic for every flow using that connection.
Not supported for DynamoDB, MongoDB, or wrapper connectors; fall back to test-mode flow runs, mock data, or the destination's own logs.
The extra per-request capture adds noticeable lag on high-volume flows (millions of records). Enable it briefly during a representative test run, or narrow the source export's criteria so a small set exercises the connection inside the debug window, then turn it off so the flow runs at full speed.

当流程因在线/离线无法解释的原因失败时——目标系统可达且凭据看似正常，但记录被拒绝并返回模糊错误或返回错误数据——可使用连接调试器捕获原始流量：

bash

celigo connections enable-debug <id> [--duration <minutes>]   # 默认15分钟，最长约1小时
celigo connections debug-logs <id>
celigo connections disable-debug <id>

捕获通过该连接的所有请求/响应，敏感字段会被掩码。每个条目包含ISO日期、请求与响应配对的UUID、使用连接的资源类型和ID，以及请求或响应体（通过共享UUID匹配请求与响应）。
仅当实际有数据流动时才会生成日志——不会为已排队但尚未处理的流程生成。捕获的日志会保留24小时（或直到被清除）。
调试是连接级别的——会捕获所有使用该连接的流程的流量。
不支持DynamoDB、MongoDB或wrapper连接器；请改用测试模式流程运行、模拟数据或目标系统自身的日志。
额外的每请求捕获会在高流量流程（数百万条记录）上造成明显延迟。仅在代表性测试运行期间短暂启用，或缩小源导出的条件，使少量记录在调试窗口内使用连接，然后关闭调试以让流程全速运行。

iClients (OAuth Credential Stores)

iClients（OAuth凭据存储）

An iClient is a reusable OAuth credential store -- it holds the client ID, client secret, scopes, and provider-specific OAuth configuration that can be shared across multiple connections. Instead of embedding OAuth app credentials directly in each connection, you create one iClient and reference it.

iClient是一个可复用的OAuth凭据存储——它存储客户端ID、客户端密钥、权限范围和提供商特定的OAuth配置，可在多个连接间共享。无需在每个连接中嵌入OAuth应用凭据，只需创建一个iClient并引用它即可。

When Do You Need an iClient?

何时需要iClient？

Scenario	iClient needed?
HTTP connection with pre-built connector that has a global iClient	Use the global iClient -- set `http._iClientId` to the connector's built-in iClient ID. No custom iClient needed.
HTTP connection with OAuth2 using a custom app registration	Yes -- create a custom iClient with your clientId/clientSecret, reference via `http._iClientId`
Salesforce connection with `packagedOAuth: false`	Yes -- store Connected App credentials in iClient
NetSuite connection with `authType: "token-auto"`	Yes -- store integration record's consumer key/secret in iClient
HTTP connection with pre-built connector (no global iClient)	Maybe -- check if the connector's auth requires one
HTTP connection with token auth (no OAuth)	No -- credentials go directly on the connection
Database, FTP, or non-OAuth connections	No

The rule of thumb: if a global iClient exists for the connector, use it. If the connection uses OAuth and you're bringing your own app registration, create a custom iClient.

场景	是否需要iClient？
带有预构建连接器且连接器有全局iClient的HTTP连接	使用全局iClient——将 `http._iClientId` 设置为连接器内置的iClient ID。无需自定义iClient。
使用自定义应用注册的OAuth2 HTTP连接	是——创建自定义iClient并设置clientId/clientSecret，通过 `http._iClientId` 引用
`packagedOAuth: false` 的Salesforce连接	是——将Connected App凭据存储在iClient中
`authType: "token-auto"` 的NetSuite连接	是——将集成记录的消费者密钥/密钥存储在iClient中
带有预构建连接器（无全局iClient）的HTTP连接	可能——检查连接器的认证是否需要iClient
使用令牌认证（无OAuth）的HTTP连接	否——凭据直接存储在连接上
数据库、FTP或非OAuth连接	否

经验法则：如果连接器存在全局iClient，请使用它。如果连接使用OAuth且你使用自己的应用注册，请创建自定义iClient。

How iClients Relate to Connections

iClient与连接的关系

┌──────────────┐       _iClientId        ┌──────────────┐
│  Connection   │ ──────────────────────► │   iClient    │
│  (HTTP/SF/NS) │                         │  (OAuth app) │
└──────────────┘                          └──────────────┘
                                                │
                                    stores clientId, clientSecret,
                                    scopes, token/refresh/revoke
                                    endpoints, provider config

Connection owns the concurrency, health monitoring, debug logging, and runtime config
iClient owns the OAuth app registration credentials and flow configuration
Multiple connections can share one iClient (e.g., multiple connections to the same OAuth app)

┌──────────────┐       _iClientId        ┌──────────────┐
│  连接   │ ──────────────────────► │   iClient    │
│  (HTTP/SF/NS) │                         │  (OAuth应用) │
└──────────────┘                          └──────────────┘
                                                │
                                    存储clientId、clientSecret、
                                    权限范围、令牌/刷新/撤销
                                    端点、提供商配置

连接负责并发设置、健康监控、调试日志和运行时配置
iClient负责OAuth应用注册凭据和流程配置
多个连接可共享一个iClient（例如，多个连接指向同一OAuth应用）

Reference fields on connections

连接上的引用字段

HTTP connections:

http._iClientId

-- when

http.auth.type

oauth

and

oauth.useIClientFields: true

NetSuite connections:
```
netsuite._iClientId
```
-- when
```
authType: "token-auto"
```
(Celigo-managed TBA)
Salesforce connections: uses iClient when
```
packagedOAuth: false
```
(custom Connected App)
MCP connections:
```
mcp._iClientId
```
-- for OAuth-based MCP server auth

HTTP连接：

http._iClientId

——当

http.auth.type

为

oauth

且

oauth.useIClientFields: true

时

NetSuite连接：
```
netsuite._iClientId
```
——当
```
authType: "token-auto"
```
（Celigo托管的TBA）时
Salesforce连接： 当
```
packagedOAuth: false
```
（自定义Connected App）时使用iClient
MCP连接：
```
mcp._iClientId
```
——基于OAuth的MCP服务器认证

How to Build an iClient

如何创建iClient

1. Determine the provider

1. 确定提供商

The

provider

field selects which auth configuration is used:

System	Provider value
Google APIs	`google`
Salesforce	`salesforce`
Azure AD / Microsoft	`azureoauth`
NetSuite (TBA)	`netsuite`
Shopify	`shopify`
Any custom OAuth2 API	`custom_oauth2`
eBay	`ebay` or `ebay-xml`

See request.yml for the full provider enum.

provider

字段选择使用的认证配置：

系统	Provider值
Google APIs	`google`
Salesforce	`salesforce`
Azure AD / Microsoft	`azureoauth`
NetSuite (TBA)	`netsuite`
Shopify	`shopify`
任意自定义OAuth2 API	`custom_oauth2`
eBay	`ebay` 或 `ebay-xml`

详见request.yml中的完整提供商枚举。

2. Build the iClient

2. 创建iClient

Use the schema for the matching provider. All schemas are in references/iclient-schemas/:

Provider	Schema	Key fields
Base fields (all)	request.yml	`provider` , `name` , `formType`
Response shape	response.yml	`_id` , `_userId` , timestamps
`custom_oauth2` , `google` , `azureoauth` , `shopify` , etc.	oauth2.yml	`clientId` , `clientSecret` , `scope` , `grantType` , token/refresh/revoke endpoints, PKCE
`netsuite`	netsuite.yml	`consumerKey` , `consumerSecret`
`salesforce`	salesforce.yml	`clientId` , `clientSecret` , optional `privateKey` for JWT bearer
`ebay` , `ebay-xml`	ebay.yml	`appId` , `devId` , `certId`
`amazonmws`	ebay.yml	`accessKeyId` , `secretKey`

Every iClient needs at minimum:

provider

and the matching provider-specific config block (

oauth2{}

netsuite{}

salesforce{}

, etc.).

使用匹配提供商的Schema。所有Schema均位于references/iclient-schemas/：

提供商	Schema	关键字段
基础字段（所有）	request.yml	`provider` 、 `name` 、 `formType`
响应格式	response.yml	`_id` 、 `_userId` 、时间戳
`custom_oauth2` 、 `google` 、 `azureoauth` 、 `shopify` 等	oauth2.yml	`clientId` 、 `clientSecret` 、 `scope` 、 `grantType` 、令牌/刷新/撤销端点、PKCE
`netsuite`	netsuite.yml	`consumerKey` 、 `consumerSecret`
`salesforce`	salesforce.yml	`clientId` 、 `clientSecret` 、可选的JWT Bearer `privateKey`
`ebay` 、 `ebay-xml`	ebay.yml	`appId` 、 `devId` 、 `certId`
`amazonmws`	ebay.yml	`accessKeyId` 、 `secretKey`

每个iClient至少需要：

provider

以及匹配的提供商特定配置块（

oauth2{}

、

netsuite{}

、

salesforce{}

等）。

3. Reference from the connection

3. 在连接中引用

After creating the iClient, set the

_iClientId

on the connection (

http._iClientId

netsuite._iClientId

mcp._iClientId

For OAuth connections, authorize via browser:

celigo connections authorize <connectionId>

创建iClient后，在连接上设置

_iClientId

（

http._iClientId

、

netsuite._iClientId

、

mcp._iClientId

）。

对于OAuth连接，通过浏览器授权：

celigo connections authorize <connectionId>

。

custom_oauth2 and JWT-Based Auth

custom_oauth2与基于JWT的认证

custom_oauth2

-- the generic OAuth2 escape hatch

custom_oauth2

——通用OAuth2解决方案

Pick a named
provider
whenever one matches the system -- it carries provider-aware defaults and the correct sub-config shape. Reach for custom_oauth2
only for OAuth2 APIs with no named provider; because nothing is preset, you supply the flow details yourself:

```
clientId
```
/
```
clientSecret
```
-- the registered app's credentials
```
scope
```
(+
```
scopeDelimiter
```
) and
```
redirectUri
```
(must match the callback registered with the provider exactly)

grantType

authorization-code

client-credentials

, or

password

token / refresh / revoke endpoints, plus
```
clientCredentialsLocation
```
(send client credentials in a basic-auth header vs the request body)
PKCE settings where the provider requires them
```
validDomainNames
```
-- required for
```
custom_oauth2
```
; list each unique domain from your auth/token/revoke URLs (host only, no scheme or path)

See oauth2.yml for the full field set.

只要系统有匹配的命名
provider
，就选择它——它带有提供商感知的默认值和正确的子配置格式。仅当OAuth2 API没有命名提供商时，才使用**

custom_oauth2

**；因为没有预设值，你需要自行提供流程细节：

```
clientId
```
/
```
clientSecret
```
——注册应用的凭据
```
scope
```
（+
```
scopeDelimiter
```
）和
```
redirectUri
```
（必须与提供商注册的回调完全匹配）

grantType

——

authorization-code

、

client-credentials

或

password

令牌/刷新/撤销端点，以及
```
clientCredentialsLocation
```
（在基础认证头或请求体中发送客户端凭据）
提供商要求的PKCE设置
```
validDomainNames
```
——
```
custom_oauth2
```
必填；列出认证/令牌/撤销URL中的每个唯一域名（仅主机名，无协议或路径）

详见oauth2.yml中的完整字段集。

JWT-based auth

基于JWT的认证

Some providers require a JWT assertion as part of the token request. Set

enableJWT: true

and populate the

jwt

block on the iClient; for Salesforce JWT bearer, supply the

privateKey

(see salesforce.yml). Handlebars templates reference the signed token via

{{{iClient.jwt.token}}}

. The

clientSecret

and private key are credentials -- the Credential Discipline & Runtime Behavior rules apply: never paste them in chat.

某些提供商要求在令牌请求中包含JWT断言。设置

enableJWT: true

并在iClient上填充

jwt

块；对于Salesforce JWT Bearer，提供

privateKey

（详见salesforce.yml）。Handlebars模板通过

{{{iClient.jwt.token}}}

引用签名令牌。

clientSecret

和私钥属于凭据——凭据规范与运行时行为规则适用：切勿在聊天中粘贴它们。

One iClient, Many Connections

一个iClient，多个连接

An iClient is the app registration, not an identity. It holds the app's

clientId

clientSecret

, while the per-user access and refresh tokens produced by actually running the OAuth flow live on the connection, not the iClient. That's why the default is one iClient, many connections -- register the app once, store it as an iClient, and point every connection that should authenticate as that app at it via

_iClientId

. Ten Salesforce connections for ten different orgs can all share one iClient: same app, ten distinct authenticated identities.

Minting a separate iClient per connection duplicates the same

clientId

clientSecret

and multiplies rotation work. Reach for distinct iClients only when connections genuinely need different registered apps -- different developer accounts, different scope grants, separate rate-limit pools, or a hard separation between environments where each has its own provider-side app.

iClient代表应用注册，而非身份。它存储应用的

clientId

clientSecret

，而实际运行OAuth流程生成的每用户访问令牌和刷新令牌存储在连接上，而非iClient上。这就是默认一个iClient对应多个连接的原因——注册一次应用，将其存储为iClient，然后让所有需要以该应用身份认证的连接通过

_iClientId

指向它。十个不同组织的Salesforce连接可共享一个iClient：同一个应用，十个不同的已认证身份。

为每个连接创建单独的iClient会重复相同的

clientId

clientSecret

，并增加轮换工作。仅当连接确实需要不同的注册应用时——不同的开发者账户、不同的权限范围授予、单独的速率限制池，或每个环境在提供商端都有自己的应用的严格环境隔离——才使用不同的iClient。

Update an iClient in Place vs Create a New One

原地更新iClient还是创建新iClient

Secret rotated (the provider reissued it, or it leaked) -> update the existing iClient in place. Every connection authenticating through it picks up the new secret with no retargeting.
The app itself changed (a different registered app, a different developer account, a move to a new client ID) -> create a new iClient. The old one stays usable for connections still on the old app; connections migrate to the new one as needed.

Smell test (mirrors connections): renewing the same app's credentials -> update in place; switching to a different app -> new iClient.

密钥已轮换（提供商重新颁发，或密钥泄露）-> 原地更新现有iClient。所有通过它认证的连接会自动获取新密钥，无需重新定向。
应用本身已更改（不同的注册应用、不同的开发者账户、迁移到新客户端ID）-> 创建新iClient。旧iClient仍可用于使用旧应用的连接；根据需要将连接迁移到新iClient。

测试方法（与连接类似）：更新同一应用的凭据->原地更新；切换到不同应用->创建新iClient。

iClient CLI Commands

iClient CLI命令

bash

undefined

bash

undefined

CRUD

CRUD操作

celigo iclients list celigo iclients get <id> celigo iclients create < iclient.json celigo iclients update <id> < iclient.json celigo iclients delete <id>

undefined

celigo iclients list celigo iclients get <id> celigo iclients create < iclient.json celigo iclients update <id> < iclient.json celigo iclients delete <id>

undefined

iClient Gotchas

iClient注意事项

_httpConnectorId
is immutable. Once an iClient is linked to an HTTP connector, it cannot be changed. Create a new iClient if you need a different connector.
provider
determines valid fields. Setting
```
provider: "netsuite"
```
means the
```
netsuite
```
block is used;
```
provider: "custom_oauth2"
```
means the
```
oauth2
```
block. Mismatching provider and config block silently ignores the wrong block.
Handlebars references use
{{{iClient.fieldName}}}
to access values stored in
```
encrypted
```
or
```
unencrypted
```
objects. For JWT:
```
{{{iClient.jwt.token}}}
```
.
validDomainNames
is required for custom OAuth2. Provide each unique domain from your auth/token/revoke URLs (without scheme or path).
Deleting an iClient breaks referencing connections. Connections that reference a deleted iClient will fail to authorize. Check for references before deleting.
Editing a shared iClient's credentials affects every referencing connection. Because one iClient backs many connections, rotating its
```
clientSecret
```
re-points OAuth for all of them at once. Confirm which connections depend on the iClient before changing it.

_httpConnectorId
不可变。iClient链接到HTTP连接器后，无法更改。如果需要不同的连接器，请创建新iClient。
provider
决定有效字段。设置
```
provider: "netsuite"
```
意味着使用
```
netsuite
```
块；
```
provider: "custom_oauth2"
```
意味着使用
```
oauth2
```
块。提供商与配置块不匹配会静默忽略错误的块。
**Handlebars引用使用
```
{{{iClient.fieldName}}}
```
**以访问存储在
```
encrypted
```
或
```
unencrypted
```
对象中的值。对于JWT：
```
{{{iClient.jwt.token}}}
```
。
validDomainNames
是自定义OAuth2的必填项。提供认证/令牌/撤销URL中的每个唯一域名（无协议或路径）。
删除iClient会破坏引用它的连接。引用已删除iClient的连接将无法授权。删除前请检查引用关系。
编辑共享iClient的凭据会影响所有引用它的连接。因为一个iClient支持多个连接，轮换其
```
clientSecret
```
会同时重新指向所有连接的OAuth。更改前请确认哪些连接依赖该iClient。

configuring-connections

Original

Translation

Configuring Connections

配置连接

Connection Types

连接类型

Quick Reference

快速参考

Connection Type Decision Matrix

连接类型决策矩阵

Minimum Required Fields

必填字段

Which Schemas to Read

参考哪些Schema

Schema Index

Schema索引

Related Skills

相关技能

How to Build a Connection

如何创建连接

1. Identify the target system

1. 确定目标系统

2. Name the connection after the system, not the operation

2. 以系统名称而非操作命名连接

3. Check for existing connections

3. 检查现有连接

Search the account for existing connections by name or keyword

按名称或关键词搜索账户中的现有连接

Show what uses a connection (exports, imports)

查看哪些资源使用了该连接（导出、导入）

Find offline connections used by enabled flows, orphaned connections

查找已启用流程使用的离线连接、孤立连接

Search marketplace for pre-built integration templates

在市场中搜索预构建的集成模板

Preview a template's connection model

预览模板的连接模型

List all connections

列出所有连接

Filter by type

按类型筛选

4. Check for a pre-built connector and global iClient

4. 检查预构建连接器和全局iClient

Search HTTP connectors (550+ apps: Shopify, Stripe, HubSpot, etc.)

搜索HTTP连接器（550+应用：Shopify、Stripe、HubSpot等）

Search trading partner connectors (EDI, AS2, VAN)

搜索贸易伙伴连接器（EDI、AS2、VAN）

5. Choose the type, auth method, and build

5. 选择类型、认证方式并创建连接

6. Test the connection

6. 测试连接

CLI Commands

CLI命令

CRUD

CRUD操作

Test connectivity

测试连接性

OAuth authorization (opens browser for OAuth flow)

OAuth授权（打开浏览器进行OAuth流程）

Debug

调试

Integration-level connection management

集成级连接管理

Replace connection across a flow's exports/imports

在流程的导出/导入中替换连接

Pre-Submit Checklist

提交前检查清单

Gotchas

注意事项

Common Errors

常见错误

Credential Discipline & Runtime Behavior

凭据规范与运行时行为

Never accept or echo real credentials in chat

切勿在聊天中接收或回显真实凭据

Online / offline -- fix the shared connection, not each flow

在线/离线——修复共享连接，而非单个流程

Connections as concurrency queues -- throughput and governance

连接作为并发队列——吞吐量与治理

Auto-recover rate-limit errors

`custom_oauth2`
-- the generic OAuth2 escape hatch

`custom_oauth2`
——通用OAuth2解决方案