Name: configuring-connections
Author: celigo

Configure Celigo connections and iClients -- credential and configuration objects that authenticate to external systems. Use when creating or editing connections, choosing auth methods, setting up OAuth, managing iClients (shared credential stores), or troubleshooting connectivity.

<! TIER:1 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 credential stores shared across connections: an OAuth app registration (client ID/secret, scopes, token endpoints) or a cloud identity (AWS IAM role, Azure service principal, Google service account). See [iClients section]( iclients shared credential stores) below. Used across flows, APIs, and tools. How to Run the Steps This skill names each step by what it reads or changes; the exact calls depend on how you reach the account. Read the one reference that matches your tools both follow the section and step names of this skill: Celigo MCP tools ( list connections , upsert connection , get schema , ...) [references/mcp.md](references/mcp.md) The celigo CLI [references/cli.md](references/cli.md) Looking up connections, connectors, templates, and iClients only reads. Creating, updating, deleting, authorizing, registering a connection on an integration, and arming a debug window all write to the account do them when the user asked for the change. Diagnosing a connection only reads: when the user asks what's wrong or what to do about it, name the change and leave it to them. A single whitelisted field is a targeted change; anything else is a full document update that sends every masked credential back exactly as read, which keeps the stored secrets, and never leaves one out see [Connection Operations]( connection operations). An iClient's update works the same way see [iClient Operations](references/iclients.md iclient operations). Connection Types Target System type Schema Notes REST/GraphQL API (with connector) http [http.yml](references/schemas/http.yml) formType: "assistant" , set httpConnectorId REST/GraphQL API (manual) http [http.yml](references/schemas/http.yml) Three form types: assistant , http , graph ql NetSuite ERP netsuite [netsuite.yml](references/schemas/netsuite.yml) Use token auto for new connections Salesforce CRM salesforce [salesforce.yml](references/schemas/salesforce.yml) Omit salesforce. iClientId to use Celigo's Connected App SQL Server, MySQL, Postgres, Oracle rdbms [rdbms.yml](references/schemas/rdbms.yml) Snowflake, BigQuery, Redshift rdbms [rdbms.yml](references/schemas/rdbms.yml) Check sub type in schema Active Directory, Databricks, DB2 jdbc [jdbc.yml](references/schemas/jdbc.yml) MongoDB/Atlas mongodb [mongodb.yml](references/schemas/mongodb.yml) DynamoDB dynamodb [dynamodb.yml](references/schemas/dynamodb.yml) FTP/SFTP/FTPS server ftp [ftp.yml](references/schemas/ftp.yml) Optional PGP encryption Amazon S3 s3 [s3.yml](references/schemas/s3.yml) Local filesystem filesystem [filesystem.yml](references/schemas/filesystem.yml) Requires agent via agentId AS2 EDI partner as2 [as2.yml](references/schemas/as2.yml) Celigo VAN (EDI hub) van [van.yml](references/schemas/van.yml) AI tool server (MCP) mcp [mcp.yml](references/schemas/mcp.yml) Stack deployed connector wrapper [wrapper.yml](references/schemas/wrapper.yml) Legacy REST (do not use) rest [rest.yml](references/schemas/rest.yml) Use http instead GraphQL steps get their editor from the connection. For a generic GraphQL API, create a graph ql connection whose base URI is the GraphQL endpoint (the connection form can't switch an existing connection to it). For a connector with a GraphQL API, bind the connection to that API with http. httpConnectorApiId every step on the connection inherits it. GraphQL steps on a connection bound to the app's REST API post to the API root and every record fails (HTTP 406 on Shopify): add a second connection bound to the GraphQL API and re point those steps to it, rather than replacing the connection on the whole flow. Patching a step's http.relativeURI to the GraphQL endpoint isn't a fix: the GraphQL editor writes / back on every save, and the step fails again. 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](references/schemas/http.yml) Any REST/GraphQL API without a connector http token , basic , oauth (the app on an iClient), custom (headers or encrypted fields); also oauth1 , jwtbearer , cookie , digest , wsse , and awsiam (an awsIam iClient) [http.yml](references/schemas/http.yml) NetSuite ERP netsuite token auto (Celigo managed TBA; only the account id) [netsuite.yml](references/schemas/netsuite.yml) Salesforce CRM salesforce OAuth through Celigo's Connected App, or the customer's via an iClient ( salesforce. iClientId ) [salesforce.yml](references/schemas/salesforce.yml) SQL databases (Postgres, MySQL, SQL Server, Oracle) rdbms Username/password + host/port [rdbms.yml](references/schemas/rdbms.yml) Snowflake / BigQuery / Redshift rdbms Snowflake: key pair or password · BigQuery: service account key · Redshift: access key pair or an AWS IAM role (no host or password) [rdbms.yml](references/schemas/rdbms.yml) MongoDB / Atlas mongodb Host list ( host:port ), username, password [mongodb.yml](references/schemas/mongodb.yml) FTP / SFTP / FTPS ftp Username/password or SSH key [ftp.yml](references/schemas/ftp.yml) Amazon S3 s3 IAM access key pair, or an IAM role through an awsIam iClient [s3.yml](references/schemas/s3.yml) MCP server mcp token , oauth (an iClient), or custom [mcp.yml](references/schemas/mcp.yml) Which of the two HTTP rows applies is determined by search, not preference: check for a pre built connector first (search the HTTP connector catalog) 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]( 4 check for a pre built connector and global iclient). Minimum Required Fields Every connection needs at minimum: name , type , and the type specific config block. Some of the fields below are required by the connection form rather than the API (each schema says which); send them anyway, or the connection won't connect. Type Required fields http (connector) name , type: "http" , http.formType: "assistant" ( assistant graphql when the API is GraphQL), http. httpConnectorId , http. httpConnectorVersionId , http. httpConnectorApiId for a connector with more than one API, http.baseURI , http.mediaType , and the fields the connector's form asks for credentials, and settings such as settings.storeName http (manual) name , type: "http" , http.baseURI , http.mediaType , http.auth.type and its credentials netsuite name , type: "netsuite" , netsuite.authType: "token auto" , netsuite.account (a non production account's id carries its suffix, such as 123456 SB1 ) salesforce name , type: "salesforce" , salesforce.oauth2FlowType (plus salesforce.username for jwtBearerToken ), salesforce.sandbox rdbms name , type: "rdbms" , rdbms.type , then that database's fields in [rdbms.yml](references/schemas/rdbms.yml) BigQuery and Redshift take no host or password ftp name , type: "ftp" , ftp.type ( ftp , sftp , ftps ), ftp.hostURI , ftp.username , and ftp.password or (SFTP) ftp.authKey an unencrypted RSA key in PEM format (OpenSSH format, passphrase protected, and PuTTY keys aren't supported); leave password out for key only SFTP s3 name , type: "s3" , s3.accessKeyId and s3.secretAccessKey , or s3.authType: "awsIam" and s3. iClientId mongodb name , type: "mongodb" , mongodb.host (an array of host:port ), mongodb.username , mongodb.password NetSuite. token auto needs only the account: Celigo supplies the OAuth client, so a token auto connection needs no iClient. REST steps (SuiteTalk records, SuiteQL, custom RESTlets) run on the same netsuite connection don't build an http connection for them (a REST step on one is refused with 422 invalid connection type ). SuiteTalk and SuiteQL need NetSuite's REST Web Services feature; a NetSuite 403 FEATURE DISABLED means it's off. netsuite.suiteAppInstalled reflects only the Celigo SuiteApp as detected at the last authentication and ignores the legacy bundle check the SuiteApp and the bundle live before calling either missing. A NetSuite token that stops working. INVALID LOGIN ATTEMPT ("Invalid login attempt.") on every step and on the test of a token based connection means NetSuite refused its token: the token was revoked or made inactive (TBA tokens don't expire), the role it's for was taken off its user, made inactive, or lost its token permission ( Log in using Access Tokens ), the integration record it was issued for was set to Blocked, or the token belongs to another account (production tokens aren't copied to a sandbox, and a refreshed sandbox needs new ones). Read the connection first and give its account, role and token by name in the answer ( netsuite.account and environment , roleName and roleId , tokenName ): they are what the NetSuite administrator checks. NetSuite's Login Audit Trail (the Detail column) says which cause it is [Diagnosing NetSuite Steps](../configuring exports/references/netsuite.md checking a refused token) has where each one is checked. Nothing in Celigo fixes it: a NetSuite administrator restores the role, or creates a new access token for the user and role the connection names ( netsuite.roleName , roleId ); a person enters the new token on the connection in the Celigo UI (a token auto connection authorizes again there, signing in with that role); then test the connection and retry the failed records. If someone offers to paste the token into chat, decline it goes only into the Celigo UI ([Credential Discipline]( never accept or echo real credentials in chat)). Salesforce. A connection authorizes through Celigo's Connected App unless salesforce. iClientId names an iClient holding the customer's own; don't send packagedOAuth , which the platform sets. Choose oauth2FlowType : refreshToken (browser authorization, the default) or jwtBearerToken (server to server; needs username and a Connected App with a digital certificate; a custom app's private key goes on its iClient). sandbox must match the org. Never write salesforce.scope : an empty list is normal, a save from the connection editor resets it, and a custom app's scopes live on its iClient. Celigo's own API (lookup caches, jobs, Celigo Storage) is reached from a flow through a connection built from one of Celigo's two connectors. Celigo APIs ( assistant: "integratorceligoapi" ) authorizes with client credentials through Celigo's own iClient and needs accessScope on cre