> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/iclients.md).

# iClients

iClients are shared OAuth 2.0 credential stores that hold client IDs, secrets, and token-endpoint configuration for a specific application or provider. Multiple connections can reference the same iClient so credentials are managed in one place.

Each iClient targets one `provider` — the provider determines which credential sub-object (`oauth2`, `netsuite`, `salesforce`, `ebay`, `amazonmws`, `azureserviceprincipal`, `googleserviceaccount`, `awsIam`) is required. Secrets are stored encrypted and returned masked as `"******"`.

### iClient schema

## The iClient object

```json
{"openapi":"3.2.0","info":{"title":"iClients","version":"1.0.0"},"components":{"schemas":{"iClient":{"type":"object","required":["_id","provider","lastModified"],"description":"iClient object as returned by the API. Includes all request fields\nplus server-managed metadata. `name` is optional on create and is\nomitted from GET responses when the iClient was created without\none (the create response echoes it as `null`).","allOf":[{"$ref":"#/components/schemas/IClientBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"$ref":"#/components/schemas/IAResourceResponse"}]},"IClientBase":{"type":"object","description":"Writable iClient fields shared by the request and response schemas.","properties":{"name":{"type":"string","description":"Display name for the iClient."},"provider":{"type":"string","description":"Authentication provider that determines which credential fields apply.","enum":["custom_oauth2","netsuite","amazonmws","awsIam","azureserviceprincipal","googleserviceaccount","integrator","salesforce","shopify","ebay-xml","microsoftbusinesscentral","google","azureoauth","squareup","zendesk","docusign","ebay","windowslive","bigcommerce","asana","box","dropbox","clover","servicenow","jobvite","twilio","certify","woocommerce"]},"published":{"type":"boolean","description":"When true, this iClient is published and available for use."},"enableJWT":{"type":"boolean","description":"Enables a JWT assertion as part of the OAuth token request.\nWhen true, `{{{iClient.jwt.token}}}` resolves to the signed\nJWT for use in the token URL request body. Requires the `jwt`\nsub-object to be configured."},"enableIClientReferences":{"type":"boolean","description":"When true, other resources can reference this iClient's fields via Handlebars expressions."},"formType":{"type":"string","enum":["assistant","http"],"description":"UI form type. Set automatically by the UI: `assistant` when\n`_httpConnectorId` is present, `http` otherwise."},"_httpConnectorId":{"type":"string","format":"objectId","description":"HTTP connector backing this iClient's guided setup."},"_httpConnectorApiId":{"type":"string","format":"objectId","description":"HTTP connector API definition linked to this iClient."},"settings":{"type":"object","description":"Connector-specific settings (e.g. region, environment, instance\nURI). Shape varies by connector."},"settingsForm":{"type":"object","description":"Dynamic UI form definition for the settings object."},"oauth2":{"type":"object","description":"OAuth 2.0 configuration. Used when `provider` is `custom_oauth2`\nor any OAuth-based provider.","properties":{"clientId":{"type":"string","description":"OAuth 2.0 client ID from the provider's app registration."},"clientSecret":{"type":"string","description":"OAuth 2.0 client secret. Returned masked as `\"******\"`; re-send that mask\non update to keep the stored secret. Required whenever `oauth2` is sent, on\ncreate and update: omitting it or sending an empty string fails with 422\n`missing_required_field` rather than clearing the secret."},"scope":{"type":"array","items":{"type":"string"},"description":"OAuth 2.0 scopes. The API accepts a string on input but\nalways returns an array in responses."},"scopeDelimiter":{"type":"string","description":"Character separating multiple scopes in a single string.\nDefaults to space per the OAuth 2.0 spec (RFC 6749)."},"redirectUri":{"type":"string","description":"OAuth 2.0 redirect URI registered with the provider."},"grantType":{"type":"string","enum":["authorizecode","password","clientcredentials"],"description":"OAuth 2.0 grant type."},"clientCredentialsLocation":{"type":"string","enum":["basicauthheader","body"],"description":"Where to include client credentials in the token request."},"accessTokenLocation":{"type":"string","enum":["url","header","body"],"description":"Where the access token is included in API requests."},"accessTokenHeaderName":{"type":["string","null"],"description":"Header name for the access token when `accessTokenLocation`\nis `header`. Defaults to `Authorization`."},"accessTokenParamName":{"type":"string","description":"Parameter name when the access token is sent as a\nquery or body parameter."},"accessTokenPath":{"type":"string","description":"JSON path to extract the access token from the token\nendpoint response body."},"refreshTokenPath":{"type":"string","description":"JSON path to extract the refresh token from the token\nendpoint response body."},"scheme":{"type":"string","description":"Authorization scheme prefix (e.g. `Bearer`, `Basic`)."},"validDomainNames":{"type":"array","items":{"type":"string"},"description":"Registrable domains (`domain.com`, `domain.co.uk` — the host with its\nsubdomains removed) of the OAuth URLs this client's credentials are\nsent to: the access token, authorization, and revoke URLs. Before an\nOAuth request leaves integrator.io, the target URL's registrable\ndomain must appear here; a full hostname never matches."},"failPath":{"type":"string","description":"Response body path to check for auth errors. Set only if\nthe API uses a field in the response body (not just HTTP\nstatus) to indicate auth failures."},"failValues":{"type":"array","items":{"type":"string"},"description":"Values at `failPath` that indicate an auth failure."},"failStatusCode":{"type":"number","description":"HTTP status code indicating an auth error, if the provider\nuses something other than 401."},"useNewAuthFailSchema":{"type":"boolean","readOnly":true,"description":"Server-managed flag. Always `true` in current responses."},"failures":{"type":"array","readOnly":true,"description":"Server-computed auth-failure detection rules derived from\n`failPath`, `failValues`, and `failStatusCode`. Present\nonly when those fields are configured.","items":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code triggering auth-failure detection."},"path":{"type":"string","description":"Response body path checked for failure values."},"values":{"type":"array","items":{"type":"string"},"description":"Values at `path` that indicate auth failure."}}}},"pkceCodeChallengeMethod":{"type":["string","null"],"enum":["plain","s256"],"description":"PKCE code challenge method (RFC 7636)."},"useIClientFields":{"type":"boolean","description":"Use legacy iClient-specific fields instead of standard\nOAuth 2.0 fields. For backward compatibility only."},"username":{"type":"string","description":"Username for the password grant type.\n\nRequired when grantType is password."},"password":{"type":"string","description":"Password for the password grant type. Returned masked\nas `\"******\"`. Re-send that value on update to keep it; it is not preserved if omitted."},"auth":{"type":"object","description":"Authorization endpoint configuration.","properties":{"uri":{"type":"string","description":"Authorization endpoint URI."},"queryParameters":{"type":"object","description":"Additional query parameters appended to the authorization\nURL. Stored encrypted (masked as `\"****\"` in responses)."}}},"token":{"type":"object","description":"Token endpoint configuration.","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method for the token request."},"uri":{"type":"string","description":"Token endpoint URI."},"body":{"type":"string","description":"Custom request body template for the token request.\nSupports Handlebars expressions."},"headers":{"description":"Custom HTTP headers for the token request. Can be an\narray of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"refresh":{"type":"object","description":"Refresh token endpoint configuration.","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method for the refresh token request."},"uri":{"type":"string","description":"Refresh token endpoint URI."},"body":{"type":"string","description":"Custom request body template for the refresh request.\nSupports Handlebars expressions."},"headers":{"description":"Custom HTTP headers for the refresh token request.\nCan be an array of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"revoke":{"type":"object","description":"Token revocation endpoint configuration (RFC 7009).","properties":{"uri":{"type":"string","description":"Revocation endpoint URI."},"body":{"type":"string","description":"Custom request body for the revocation request."},"headers":{"description":"Custom HTTP headers for the revocation request.\nCan be an array of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"unencrypted":{"type":"object","description":"Non-sensitive key-value pairs accessible via iClient\nreferences (e.g. email, account ID, role)."},"encrypted":{"type":["object","string"],"description":"Sensitive key-value pairs stored with AES-256 encryption.\nSend an object when writing; API responses mask the whole\nvalue as the string `\"******\"`."}}},"netsuite":{"type":"object","description":"NetSuite token-based authentication credentials.","properties":{"consumerKey":{"type":"string","description":"NetSuite consumer key. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"consumerSecret":{"type":"string","description":"NetSuite consumer secret. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."}}},"salesforce":{"type":"object","description":"Salesforce authentication credentials.","properties":{"clientId":{"type":"string","description":"Salesforce connected app client ID."},"clientSecret":{"type":"string","description":"Salesforce client secret. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"apiToken":{"type":"string","description":"Salesforce security token appended to the password for\nusername-password auth flows."},"privateKey":{"type":"string","description":"Private key for Salesforce JWT bearer token flows (PEM\nformat). Returned masked as `\"******\"`."},"publicKey":{"type":"string","description":"Public key corresponding to `privateKey` (PEM format)."}}},"ebay":{"type":"object","description":"eBay REST/Trading API authentication credentials.","properties":{"appId":{"type":"string","description":"eBay application ID from the eBay Developer Program."},"devId":{"type":"string","description":"eBay developer ID from the eBay Developer Program."},"certId":{"type":"string","description":"eBay certificate ID. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"ruName":{"type":"string","description":"eBay Redirect URL Name (RuName) — the auth redirect\ntarget registered in the eBay Developer Program."}}},"amazonmws":{"type":"object","description":"Amazon Marketplace Web Service (MWS) authentication credentials.","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID for MWS API requests."},"secretKey":{"type":"string","description":"AWS secret key. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."}}},"azureserviceprincipal":{"type":"object","description":"Microsoft Entra (Azure AD) service principal credentials. Required\nwhen `provider` is `azureserviceprincipal`. One iClient of this\nprovider can back Azure Data Lake Storage Gen2, Microsoft SQL Server\n(cloud) and Azure Synapse Analytics connections; the connection forms\noffer the certificate method from Microsoft SQL Server connections\nonly.","required":["clientId","tenantId"],"properties":{"authMethod":{"type":"string","enum":["client-secret","certificate"],"default":"client-secret","description":"Which credential the service principal presents. Defaults to\n`client-secret` when omitted. Each method rejects the other\nmethod's credential fields on save. Changing the method on an\nupdate replaces the credential: send the new method's credential\nand drop the old one."},"clientId":{"type":"string","description":"Azure AD application (client) ID."},"clientSecret":{"type":"string","description":"Azure AD client secret. Required when `authMethod` is\n`client-secret` (or omitted). Returned masked as `\"******\"`.\nOn update the stored secret is kept when the field is omitted or\nre-sent as the mask; only a new value replaces it."},"certificate":{"type":"string","writeOnly":true,"description":"PEM bundle (certificate + private key) for certificate auth.\nRequired when `authMethod` is `certificate`; rejected under\n`client-secret`. Maximum 20 KiB of PEM text. Never returned in\nresponses, not even masked. On update the stored PEM is kept when\nthe field is omitted; only a new value replaces it."},"certificatePassword":{"type":"string","description":"Passphrase for an encrypted private key inside `certificate`.\nRequired exactly when the PEM's key is encrypted; rejected when\nit is not. Maximum 256 bytes. Returned masked when set."},"tenantId":{"type":"string","description":"Azure AD tenant (directory) ID."}}},"googleserviceaccount":{"type":"object","description":"Google Cloud service-account credentials. Required when `provider` is\n`googleserviceaccount`. Send the raw JSON key file in\n`serviceAccountJSON`; the server parses out `project_id`,\n`client_email`, and `private_key` and stores them (the private key\nencrypted). Responses return only `clientEmail`.","properties":{"serviceAccountJSON":{"type":"string","writeOnly":true,"description":"Google service-account key file, sent as a JSON string. The save\nreads `project_id`, `client_email`, and a `private_key` that\nincludes its PEM armor (its BEGIN and END PRIVATE KEY lines).\nMissing, empty, or incomplete JSON fails with 422\n`invalid_json_key`. Send the full key on every create and every\nupdate — omitting it or sending `\"******\"` fails the same way."},"clientEmail":{"type":"string","readOnly":true,"description":"Service-account email parsed from the key file — the only field echoed in responses."}}},"awsIam":{"type":"object","description":"AWS IAM cross-account role credentials. Required when `provider` is `awsIam`\n(omitting the object fails with 422 `missing_required_field` \"The awsIam sub-schema is\nrequired\"). Celigo assumes `roleArn` using `externalId` as the trust-policy external ID.\nThe iClient itself saves with `externalId` alone; the connection that references it\nadds its own rules on `roleArn` (see that field). One iClient serves one connection\nfamily — Amazon S3, Amazon Redshift, or the AWS HTTP connectors — because each family\naccepts only roles named with its own prefix.","required":["externalId"],"properties":{"externalId":{"type":"string","minLength":2,"maxLength":1224,"pattern":"^[a-zA-Z0-9+=,.@:/_-]+$","description":"External ID Celigo presents when assuming the role; must match the\n`sts:ExternalId` condition in the role's trust policy. Fixed at creation: a `PUT`\nthat sends a different value keeps the stored one. A value outside the allowed\ncharacter set or length fails with 422 `invalid_field_value`."},"roleArn":{"type":"string","pattern":"^arn:[a-z-]+:iam::\\d{12}:role/[A-Za-z0-9+=,.@_/-]{1,576}$","description":"ARN of the AWS IAM role to assume for cross-account access. Optional on the iClient\n(a malformed ARN fails with 422 `invalid_field_value`), but no connection in IAM-role\nmode can be saved against this iClient until it is set, and each connection family\naccepts only its own role-name prefix: `celigo-file-adaptor-` for Amazon S3,\n`celigo-data-warehouse-adaptor-` for Amazon Redshift, `celigo-http-adaptor-` for the\nAWS HTTP connectors (`auth.type` `awsiam`)."}}},"jwt":{"type":"object","description":"JWT assertion configuration. Used when `enableJWT` is true to\ngenerate a signed JWT for inclusion in OAuth token requests via\n`{{{iClient.jwt.token}}}`.","properties":{"signatureMethod":{"type":"string","enum":["hmac-sha256","hmac-sha384","hmac-sha512","rsa-sha256","rsa-sha384","rsa-sha512","es256","es384","es512","ps256","ps384","ps512"],"description":"Algorithm used to sign the JWT. HMAC methods sign with `secret`;\nRSA/ECDSA/PSS methods sign with `privateKey`."},"payload":{"description":"JWT payload claims. Can be a JSON object or a stringified\nJSON template with Handlebars expressions."},"headers":{"description":"JWT header claims. Can be a JSON object or a stringified\nJSON template with Handlebars expressions."},"privateKey":{"type":"string","description":"Private key for signing the JWT. Returned masked as\n`\"******\"`. Re-send that value on update to keep it; it is not preserved if omitted."},"token":{"type":"string","readOnly":true,"description":"Server-computed signed JWT token. Returned masked as\n`\"******\"` in responses."},"secret":{"type":"string","description":"Shared secret for HMAC-based JWT signing (e.g. HS256).\nReturned masked as `\"******\"`. Re-send that value on update to\nkeep it; it is not preserved if omitted."},"isSecretBase64Encoded":{"type":"boolean","description":"When true, the `secret` value is Base64-encoded."}}}},"if":{"properties":{"provider":{"const":"awsIam"}},"required":["provider"]},"then":{"required":["awsIam"]}},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"deletedAt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Timestamp when the resource was soft-deleted. When null or absent, the resource is active."}},"required":["_id"]},"IAResourceResponse":{"type":"object","description":"Integration app response fields for resources that are part of integration apps","properties":{"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Reference to the specific integration instance that contains this resource.\n\nThis field is only populated for resources that are part of an integration app\ninstallation. It contains the unique identifier (_id) of the integration\nresource that was installed in the account.\n\nThe integration instance represents a specific installed instance of an\nintegration app, with its own configuration, settings, and runtime environment.\n\nThis reference enables:\n- Tracing the resource back to its parent integration instance\n- Permission and access control based on integration ownership\n- Lifecycle management (enabling/disabling, updating, or uninstalling)\n"},"_connectorId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration App (connector) that defines this resource. Present only on resources an\nIntegration App owns. The app locks parts of these documents, and a PUT that changes a\nlocked field answers 200 but keeps the stored value, so read the document back to confirm\na change."}}}}}}
```

## List iClients

> Returns all iClients in the account. Does not paginate — all\
> iClients are returned in a single response.

```json
{"openapi":"3.2.0","info":{"title":"iClients","version":"1.0.0"},"tags":[{"name":"iClients","description":"iClients are shared OAuth 2.0 credential stores that hold client\nIDs, secrets, and token-endpoint configuration for a specific\napplication or provider. Multiple connections can reference the\nsame iClient so credentials are managed in one place.\n\nEach iClient targets one `provider` — the provider determines\nwhich credential sub-object (`oauth2`, `netsuite`, `salesforce`,\n`ebay`, `amazonmws`, `azureserviceprincipal`, `googleserviceaccount`,\n`awsIam`) is required.\nSecrets are stored encrypted and returned masked as `\"******\"`.\n\n## iClient schema\n\n{% openapi-schemas spec=\"iclient\" schemas=\"iClient\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"After":{"name":"after","in":"query","required":false,"description":"Opaque cursor for forward pagination. Pass the value from the `Link`\nresponse header (`rel=\"next\"`) to fetch the next page.","schema":{"type":"string"}}},"schemas":{"iClient":{"type":"object","required":["_id","provider","lastModified"],"description":"iClient object as returned by the API. Includes all request fields\nplus server-managed metadata. `name` is optional on create and is\nomitted from GET responses when the iClient was created without\none (the create response echoes it as `null`).","allOf":[{"$ref":"#/components/schemas/IClientBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"$ref":"#/components/schemas/IAResourceResponse"}]},"IClientBase":{"type":"object","description":"Writable iClient fields shared by the request and response schemas.","properties":{"name":{"type":"string","description":"Display name for the iClient."},"provider":{"type":"string","description":"Authentication provider that determines which credential fields apply.","enum":["custom_oauth2","netsuite","amazonmws","awsIam","azureserviceprincipal","googleserviceaccount","integrator","salesforce","shopify","ebay-xml","microsoftbusinesscentral","google","azureoauth","squareup","zendesk","docusign","ebay","windowslive","bigcommerce","asana","box","dropbox","clover","servicenow","jobvite","twilio","certify","woocommerce"]},"published":{"type":"boolean","description":"When true, this iClient is published and available for use."},"enableJWT":{"type":"boolean","description":"Enables a JWT assertion as part of the OAuth token request.\nWhen true, `{{{iClient.jwt.token}}}` resolves to the signed\nJWT for use in the token URL request body. Requires the `jwt`\nsub-object to be configured."},"enableIClientReferences":{"type":"boolean","description":"When true, other resources can reference this iClient's fields via Handlebars expressions."},"formType":{"type":"string","enum":["assistant","http"],"description":"UI form type. Set automatically by the UI: `assistant` when\n`_httpConnectorId` is present, `http` otherwise."},"_httpConnectorId":{"type":"string","format":"objectId","description":"HTTP connector backing this iClient's guided setup."},"_httpConnectorApiId":{"type":"string","format":"objectId","description":"HTTP connector API definition linked to this iClient."},"settings":{"type":"object","description":"Connector-specific settings (e.g. region, environment, instance\nURI). Shape varies by connector."},"settingsForm":{"type":"object","description":"Dynamic UI form definition for the settings object."},"oauth2":{"type":"object","description":"OAuth 2.0 configuration. Used when `provider` is `custom_oauth2`\nor any OAuth-based provider.","properties":{"clientId":{"type":"string","description":"OAuth 2.0 client ID from the provider's app registration."},"clientSecret":{"type":"string","description":"OAuth 2.0 client secret. Returned masked as `\"******\"`; re-send that mask\non update to keep the stored secret. Required whenever `oauth2` is sent, on\ncreate and update: omitting it or sending an empty string fails with 422\n`missing_required_field` rather than clearing the secret."},"scope":{"type":"array","items":{"type":"string"},"description":"OAuth 2.0 scopes. The API accepts a string on input but\nalways returns an array in responses."},"scopeDelimiter":{"type":"string","description":"Character separating multiple scopes in a single string.\nDefaults to space per the OAuth 2.0 spec (RFC 6749)."},"redirectUri":{"type":"string","description":"OAuth 2.0 redirect URI registered with the provider."},"grantType":{"type":"string","enum":["authorizecode","password","clientcredentials"],"description":"OAuth 2.0 grant type."},"clientCredentialsLocation":{"type":"string","enum":["basicauthheader","body"],"description":"Where to include client credentials in the token request."},"accessTokenLocation":{"type":"string","enum":["url","header","body"],"description":"Where the access token is included in API requests."},"accessTokenHeaderName":{"type":["string","null"],"description":"Header name for the access token when `accessTokenLocation`\nis `header`. Defaults to `Authorization`."},"accessTokenParamName":{"type":"string","description":"Parameter name when the access token is sent as a\nquery or body parameter."},"accessTokenPath":{"type":"string","description":"JSON path to extract the access token from the token\nendpoint response body."},"refreshTokenPath":{"type":"string","description":"JSON path to extract the refresh token from the token\nendpoint response body."},"scheme":{"type":"string","description":"Authorization scheme prefix (e.g. `Bearer`, `Basic`)."},"validDomainNames":{"type":"array","items":{"type":"string"},"description":"Registrable domains (`domain.com`, `domain.co.uk` — the host with its\nsubdomains removed) of the OAuth URLs this client's credentials are\nsent to: the access token, authorization, and revoke URLs. Before an\nOAuth request leaves integrator.io, the target URL's registrable\ndomain must appear here; a full hostname never matches."},"failPath":{"type":"string","description":"Response body path to check for auth errors. Set only if\nthe API uses a field in the response body (not just HTTP\nstatus) to indicate auth failures."},"failValues":{"type":"array","items":{"type":"string"},"description":"Values at `failPath` that indicate an auth failure."},"failStatusCode":{"type":"number","description":"HTTP status code indicating an auth error, if the provider\nuses something other than 401."},"useNewAuthFailSchema":{"type":"boolean","readOnly":true,"description":"Server-managed flag. Always `true` in current responses."},"failures":{"type":"array","readOnly":true,"description":"Server-computed auth-failure detection rules derived from\n`failPath`, `failValues`, and `failStatusCode`. Present\nonly when those fields are configured.","items":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code triggering auth-failure detection."},"path":{"type":"string","description":"Response body path checked for failure values."},"values":{"type":"array","items":{"type":"string"},"description":"Values at `path` that indicate auth failure."}}}},"pkceCodeChallengeMethod":{"type":["string","null"],"enum":["plain","s256"],"description":"PKCE code challenge method (RFC 7636)."},"useIClientFields":{"type":"boolean","description":"Use legacy iClient-specific fields instead of standard\nOAuth 2.0 fields. For backward compatibility only."},"username":{"type":"string","description":"Username for the password grant type.\n\nRequired when grantType is password."},"password":{"type":"string","description":"Password for the password grant type. Returned masked\nas `\"******\"`. Re-send that value on update to keep it; it is not preserved if omitted."},"auth":{"type":"object","description":"Authorization endpoint configuration.","properties":{"uri":{"type":"string","description":"Authorization endpoint URI."},"queryParameters":{"type":"object","description":"Additional query parameters appended to the authorization\nURL. Stored encrypted (masked as `\"****\"` in responses)."}}},"token":{"type":"object","description":"Token endpoint configuration.","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method for the token request."},"uri":{"type":"string","description":"Token endpoint URI."},"body":{"type":"string","description":"Custom request body template for the token request.\nSupports Handlebars expressions."},"headers":{"description":"Custom HTTP headers for the token request. Can be an\narray of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"refresh":{"type":"object","description":"Refresh token endpoint configuration.","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method for the refresh token request."},"uri":{"type":"string","description":"Refresh token endpoint URI."},"body":{"type":"string","description":"Custom request body template for the refresh request.\nSupports Handlebars expressions."},"headers":{"description":"Custom HTTP headers for the refresh token request.\nCan be an array of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"revoke":{"type":"object","description":"Token revocation endpoint configuration (RFC 7009).","properties":{"uri":{"type":"string","description":"Revocation endpoint URI."},"body":{"type":"string","description":"Custom request body for the revocation request."},"headers":{"description":"Custom HTTP headers for the revocation request.\nCan be an array of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"unencrypted":{"type":"object","description":"Non-sensitive key-value pairs accessible via iClient\nreferences (e.g. email, account ID, role)."},"encrypted":{"type":["object","string"],"description":"Sensitive key-value pairs stored with AES-256 encryption.\nSend an object when writing; API responses mask the whole\nvalue as the string `\"******\"`."}}},"netsuite":{"type":"object","description":"NetSuite token-based authentication credentials.","properties":{"consumerKey":{"type":"string","description":"NetSuite consumer key. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"consumerSecret":{"type":"string","description":"NetSuite consumer secret. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."}}},"salesforce":{"type":"object","description":"Salesforce authentication credentials.","properties":{"clientId":{"type":"string","description":"Salesforce connected app client ID."},"clientSecret":{"type":"string","description":"Salesforce client secret. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"apiToken":{"type":"string","description":"Salesforce security token appended to the password for\nusername-password auth flows."},"privateKey":{"type":"string","description":"Private key for Salesforce JWT bearer token flows (PEM\nformat). Returned masked as `\"******\"`."},"publicKey":{"type":"string","description":"Public key corresponding to `privateKey` (PEM format)."}}},"ebay":{"type":"object","description":"eBay REST/Trading API authentication credentials.","properties":{"appId":{"type":"string","description":"eBay application ID from the eBay Developer Program."},"devId":{"type":"string","description":"eBay developer ID from the eBay Developer Program."},"certId":{"type":"string","description":"eBay certificate ID. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"ruName":{"type":"string","description":"eBay Redirect URL Name (RuName) — the auth redirect\ntarget registered in the eBay Developer Program."}}},"amazonmws":{"type":"object","description":"Amazon Marketplace Web Service (MWS) authentication credentials.","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID for MWS API requests."},"secretKey":{"type":"string","description":"AWS secret key. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."}}},"azureserviceprincipal":{"type":"object","description":"Microsoft Entra (Azure AD) service principal credentials. Required\nwhen `provider` is `azureserviceprincipal`. One iClient of this\nprovider can back Azure Data Lake Storage Gen2, Microsoft SQL Server\n(cloud) and Azure Synapse Analytics connections; the connection forms\noffer the certificate method from Microsoft SQL Server connections\nonly.","required":["clientId","tenantId"],"properties":{"authMethod":{"type":"string","enum":["client-secret","certificate"],"default":"client-secret","description":"Which credential the service principal presents. Defaults to\n`client-secret` when omitted. Each method rejects the other\nmethod's credential fields on save. Changing the method on an\nupdate replaces the credential: send the new method's credential\nand drop the old one."},"clientId":{"type":"string","description":"Azure AD application (client) ID."},"clientSecret":{"type":"string","description":"Azure AD client secret. Required when `authMethod` is\n`client-secret` (or omitted). Returned masked as `\"******\"`.\nOn update the stored secret is kept when the field is omitted or\nre-sent as the mask; only a new value replaces it."},"certificate":{"type":"string","writeOnly":true,"description":"PEM bundle (certificate + private key) for certificate auth.\nRequired when `authMethod` is `certificate`; rejected under\n`client-secret`. Maximum 20 KiB of PEM text. Never returned in\nresponses, not even masked. On update the stored PEM is kept when\nthe field is omitted; only a new value replaces it."},"certificatePassword":{"type":"string","description":"Passphrase for an encrypted private key inside `certificate`.\nRequired exactly when the PEM's key is encrypted; rejected when\nit is not. Maximum 256 bytes. Returned masked when set."},"tenantId":{"type":"string","description":"Azure AD tenant (directory) ID."}}},"googleserviceaccount":{"type":"object","description":"Google Cloud service-account credentials. Required when `provider` is\n`googleserviceaccount`. Send the raw JSON key file in\n`serviceAccountJSON`; the server parses out `project_id`,\n`client_email`, and `private_key` and stores them (the private key\nencrypted). Responses return only `clientEmail`.","properties":{"serviceAccountJSON":{"type":"string","writeOnly":true,"description":"Google service-account key file, sent as a JSON string. The save\nreads `project_id`, `client_email`, and a `private_key` that\nincludes its PEM armor (its BEGIN and END PRIVATE KEY lines).\nMissing, empty, or incomplete JSON fails with 422\n`invalid_json_key`. Send the full key on every create and every\nupdate — omitting it or sending `\"******\"` fails the same way."},"clientEmail":{"type":"string","readOnly":true,"description":"Service-account email parsed from the key file — the only field echoed in responses."}}},"awsIam":{"type":"object","description":"AWS IAM cross-account role credentials. Required when `provider` is `awsIam`\n(omitting the object fails with 422 `missing_required_field` \"The awsIam sub-schema is\nrequired\"). Celigo assumes `roleArn` using `externalId` as the trust-policy external ID.\nThe iClient itself saves with `externalId` alone; the connection that references it\nadds its own rules on `roleArn` (see that field). One iClient serves one connection\nfamily — Amazon S3, Amazon Redshift, or the AWS HTTP connectors — because each family\naccepts only roles named with its own prefix.","required":["externalId"],"properties":{"externalId":{"type":"string","minLength":2,"maxLength":1224,"pattern":"^[a-zA-Z0-9+=,.@:/_-]+$","description":"External ID Celigo presents when assuming the role; must match the\n`sts:ExternalId` condition in the role's trust policy. Fixed at creation: a `PUT`\nthat sends a different value keeps the stored one. A value outside the allowed\ncharacter set or length fails with 422 `invalid_field_value`."},"roleArn":{"type":"string","pattern":"^arn:[a-z-]+:iam::\\d{12}:role/[A-Za-z0-9+=,.@_/-]{1,576}$","description":"ARN of the AWS IAM role to assume for cross-account access. Optional on the iClient\n(a malformed ARN fails with 422 `invalid_field_value`), but no connection in IAM-role\nmode can be saved against this iClient until it is set, and each connection family\naccepts only its own role-name prefix: `celigo-file-adaptor-` for Amazon S3,\n`celigo-data-warehouse-adaptor-` for Amazon Redshift, `celigo-http-adaptor-` for the\nAWS HTTP connectors (`auth.type` `awsiam`)."}}},"jwt":{"type":"object","description":"JWT assertion configuration. Used when `enableJWT` is true to\ngenerate a signed JWT for inclusion in OAuth token requests via\n`{{{iClient.jwt.token}}}`.","properties":{"signatureMethod":{"type":"string","enum":["hmac-sha256","hmac-sha384","hmac-sha512","rsa-sha256","rsa-sha384","rsa-sha512","es256","es384","es512","ps256","ps384","ps512"],"description":"Algorithm used to sign the JWT. HMAC methods sign with `secret`;\nRSA/ECDSA/PSS methods sign with `privateKey`."},"payload":{"description":"JWT payload claims. Can be a JSON object or a stringified\nJSON template with Handlebars expressions."},"headers":{"description":"JWT header claims. Can be a JSON object or a stringified\nJSON template with Handlebars expressions."},"privateKey":{"type":"string","description":"Private key for signing the JWT. Returned masked as\n`\"******\"`. Re-send that value on update to keep it; it is not preserved if omitted."},"token":{"type":"string","readOnly":true,"description":"Server-computed signed JWT token. Returned masked as\n`\"******\"` in responses."},"secret":{"type":"string","description":"Shared secret for HMAC-based JWT signing (e.g. HS256).\nReturned masked as `\"******\"`. Re-send that value on update to\nkeep it; it is not preserved if omitted."},"isSecretBase64Encoded":{"type":"boolean","description":"When true, the `secret` value is Base64-encoded."}}}},"if":{"properties":{"provider":{"const":"awsIam"}},"required":["provider"]},"then":{"required":["awsIam"]}},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"deletedAt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Timestamp when the resource was soft-deleted. When null or absent, the resource is active."}},"required":["_id"]},"IAResourceResponse":{"type":"object","description":"Integration app response fields for resources that are part of integration apps","properties":{"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Reference to the specific integration instance that contains this resource.\n\nThis field is only populated for resources that are part of an integration app\ninstallation. It contains the unique identifier (_id) of the integration\nresource that was installed in the account.\n\nThe integration instance represents a specific installed instance of an\nintegration app, with its own configuration, settings, and runtime environment.\n\nThis reference enables:\n- Tracing the resource back to its parent integration instance\n- Permission and access control based on integration ownership\n- Lifecycle management (enabling/disabling, updating, or uninstalling)\n"},"_connectorId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration App (connector) that defines this resource. Present only on resources an\nIntegration App owns. The app locks parts of these documents, and a PUT that changes a\nlocked field answers 200 but keeps the stored value, so read the document back to confirm\na change."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/iclients":{"get":{"summary":"List iClients","description":"Returns all iClients in the account. Does not paginate — all\niClients are returned in a single response.","operationId":"listIClients","tags":["iClients"],"parameters":[{"name":"limit","in":"query","description":"Maximum number of records to return per page.","schema":{"type":"integer","minimum":1}},{"$ref":"#/components/parameters/After"}],"responses":{"200":{"description":"List of iClients (may be empty).","headers":{"Link":{"description":"RFC-5988 pagination links. When more pages remain, includes a `<...>; rel=\"next\"` entry;\nabsent on the final page.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/iClient"}}}}},"204":{"description":"No iClients exist in the account."},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Create an iClient

> Creates a new iClient. The \`provider\` field is required and\
> determines which credential sub-object must be populated.

```json
{"openapi":"3.2.0","info":{"title":"iClients","version":"1.0.0"},"tags":[{"name":"iClients","description":"iClients are shared OAuth 2.0 credential stores that hold client\nIDs, secrets, and token-endpoint configuration for a specific\napplication or provider. Multiple connections can reference the\nsame iClient so credentials are managed in one place.\n\nEach iClient targets one `provider` — the provider determines\nwhich credential sub-object (`oauth2`, `netsuite`, `salesforce`,\n`ebay`, `amazonmws`, `azureserviceprincipal`, `googleserviceaccount`,\n`awsIam`) is required.\nSecrets are stored encrypted and returned masked as `\"******\"`.\n\n## iClient schema\n\n{% openapi-schemas spec=\"iclient\" schemas=\"iClient\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"iClient configuration. The shape varies by `provider` — each provider\nrequires its own credential sub-object (`oauth2`, `netsuite`,\n`salesforce`, `ebay`, `amazonmws`, `azureserviceprincipal`,\n`googleserviceaccount`, `awsIam`).\nFor `custom_oauth2`, credentials go in the `oauth2` sub-object.\nSecrets (`clientSecret`, `privateKey`, and so on) come back masked\nas `\"******\"`. Re-send that mask on update to keep the stored\nsecret; omitting it does not. Two providers differ. A Google\nservice account: `serviceAccountJSON` is not returned, and every\nupdate must send the full key — the mask or an omission fails with\n422 `invalid_json_key`. An Azure service principal: the stored\n`clientSecret` or `certificate` is kept when its field is omitted\non update, and only a new value replaces it (`certificate` is never\nreturned, not even masked).","required":["provider"],"allOf":[{"$ref":"#/components/schemas/IClientBase"}]},"IClientBase":{"type":"object","description":"Writable iClient fields shared by the request and response schemas.","properties":{"name":{"type":"string","description":"Display name for the iClient."},"provider":{"type":"string","description":"Authentication provider that determines which credential fields apply.","enum":["custom_oauth2","netsuite","amazonmws","awsIam","azureserviceprincipal","googleserviceaccount","integrator","salesforce","shopify","ebay-xml","microsoftbusinesscentral","google","azureoauth","squareup","zendesk","docusign","ebay","windowslive","bigcommerce","asana","box","dropbox","clover","servicenow","jobvite","twilio","certify","woocommerce"]},"published":{"type":"boolean","description":"When true, this iClient is published and available for use."},"enableJWT":{"type":"boolean","description":"Enables a JWT assertion as part of the OAuth token request.\nWhen true, `{{{iClient.jwt.token}}}` resolves to the signed\nJWT for use in the token URL request body. Requires the `jwt`\nsub-object to be configured."},"enableIClientReferences":{"type":"boolean","description":"When true, other resources can reference this iClient's fields via Handlebars expressions."},"formType":{"type":"string","enum":["assistant","http"],"description":"UI form type. Set automatically by the UI: `assistant` when\n`_httpConnectorId` is present, `http` otherwise."},"_httpConnectorId":{"type":"string","format":"objectId","description":"HTTP connector backing this iClient's guided setup."},"_httpConnectorApiId":{"type":"string","format":"objectId","description":"HTTP connector API definition linked to this iClient."},"settings":{"type":"object","description":"Connector-specific settings (e.g. region, environment, instance\nURI). Shape varies by connector."},"settingsForm":{"type":"object","description":"Dynamic UI form definition for the settings object."},"oauth2":{"type":"object","description":"OAuth 2.0 configuration. Used when `provider` is `custom_oauth2`\nor any OAuth-based provider.","properties":{"clientId":{"type":"string","description":"OAuth 2.0 client ID from the provider's app registration."},"clientSecret":{"type":"string","description":"OAuth 2.0 client secret. Returned masked as `\"******\"`; re-send that mask\non update to keep the stored secret. Required whenever `oauth2` is sent, on\ncreate and update: omitting it or sending an empty string fails with 422\n`missing_required_field` rather than clearing the secret."},"scope":{"type":"array","items":{"type":"string"},"description":"OAuth 2.0 scopes. The API accepts a string on input but\nalways returns an array in responses."},"scopeDelimiter":{"type":"string","description":"Character separating multiple scopes in a single string.\nDefaults to space per the OAuth 2.0 spec (RFC 6749)."},"redirectUri":{"type":"string","description":"OAuth 2.0 redirect URI registered with the provider."},"grantType":{"type":"string","enum":["authorizecode","password","clientcredentials"],"description":"OAuth 2.0 grant type."},"clientCredentialsLocation":{"type":"string","enum":["basicauthheader","body"],"description":"Where to include client credentials in the token request."},"accessTokenLocation":{"type":"string","enum":["url","header","body"],"description":"Where the access token is included in API requests."},"accessTokenHeaderName":{"type":["string","null"],"description":"Header name for the access token when `accessTokenLocation`\nis `header`. Defaults to `Authorization`."},"accessTokenParamName":{"type":"string","description":"Parameter name when the access token is sent as a\nquery or body parameter."},"accessTokenPath":{"type":"string","description":"JSON path to extract the access token from the token\nendpoint response body."},"refreshTokenPath":{"type":"string","description":"JSON path to extract the refresh token from the token\nendpoint response body."},"scheme":{"type":"string","description":"Authorization scheme prefix (e.g. `Bearer`, `Basic`)."},"validDomainNames":{"type":"array","items":{"type":"string"},"description":"Registrable domains (`domain.com`, `domain.co.uk` — the host with its\nsubdomains removed) of the OAuth URLs this client's credentials are\nsent to: the access token, authorization, and revoke URLs. Before an\nOAuth request leaves integrator.io, the target URL's registrable\ndomain must appear here; a full hostname never matches."},"failPath":{"type":"string","description":"Response body path to check for auth errors. Set only if\nthe API uses a field in the response body (not just HTTP\nstatus) to indicate auth failures."},"failValues":{"type":"array","items":{"type":"string"},"description":"Values at `failPath` that indicate an auth failure."},"failStatusCode":{"type":"number","description":"HTTP status code indicating an auth error, if the provider\nuses something other than 401."},"useNewAuthFailSchema":{"type":"boolean","readOnly":true,"description":"Server-managed flag. Always `true` in current responses."},"failures":{"type":"array","readOnly":true,"description":"Server-computed auth-failure detection rules derived from\n`failPath`, `failValues`, and `failStatusCode`. Present\nonly when those fields are configured.","items":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code triggering auth-failure detection."},"path":{"type":"string","description":"Response body path checked for failure values."},"values":{"type":"array","items":{"type":"string"},"description":"Values at `path` that indicate auth failure."}}}},"pkceCodeChallengeMethod":{"type":["string","null"],"enum":["plain","s256"],"description":"PKCE code challenge method (RFC 7636)."},"useIClientFields":{"type":"boolean","description":"Use legacy iClient-specific fields instead of standard\nOAuth 2.0 fields. For backward compatibility only."},"username":{"type":"string","description":"Username for the password grant type.\n\nRequired when grantType is password."},"password":{"type":"string","description":"Password for the password grant type. Returned masked\nas `\"******\"`. Re-send that value on update to keep it; it is not preserved if omitted."},"auth":{"type":"object","description":"Authorization endpoint configuration.","properties":{"uri":{"type":"string","description":"Authorization endpoint URI."},"queryParameters":{"type":"object","description":"Additional query parameters appended to the authorization\nURL. Stored encrypted (masked as `\"****\"` in responses)."}}},"token":{"type":"object","description":"Token endpoint configuration.","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method for the token request."},"uri":{"type":"string","description":"Token endpoint URI."},"body":{"type":"string","description":"Custom request body template for the token request.\nSupports Handlebars expressions."},"headers":{"description":"Custom HTTP headers for the token request. Can be an\narray of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"refresh":{"type":"object","description":"Refresh token endpoint configuration.","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method for the refresh token request."},"uri":{"type":"string","description":"Refresh token endpoint URI."},"body":{"type":"string","description":"Custom request body template for the refresh request.\nSupports Handlebars expressions."},"headers":{"description":"Custom HTTP headers for the refresh token request.\nCan be an array of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"revoke":{"type":"object","description":"Token revocation endpoint configuration (RFC 7009).","properties":{"uri":{"type":"string","description":"Revocation endpoint URI."},"body":{"type":"string","description":"Custom request body for the revocation request."},"headers":{"description":"Custom HTTP headers for the revocation request.\nCan be an array of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"unencrypted":{"type":"object","description":"Non-sensitive key-value pairs accessible via iClient\nreferences (e.g. email, account ID, role)."},"encrypted":{"type":["object","string"],"description":"Sensitive key-value pairs stored with AES-256 encryption.\nSend an object when writing; API responses mask the whole\nvalue as the string `\"******\"`."}}},"netsuite":{"type":"object","description":"NetSuite token-based authentication credentials.","properties":{"consumerKey":{"type":"string","description":"NetSuite consumer key. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"consumerSecret":{"type":"string","description":"NetSuite consumer secret. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."}}},"salesforce":{"type":"object","description":"Salesforce authentication credentials.","properties":{"clientId":{"type":"string","description":"Salesforce connected app client ID."},"clientSecret":{"type":"string","description":"Salesforce client secret. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"apiToken":{"type":"string","description":"Salesforce security token appended to the password for\nusername-password auth flows."},"privateKey":{"type":"string","description":"Private key for Salesforce JWT bearer token flows (PEM\nformat). Returned masked as `\"******\"`."},"publicKey":{"type":"string","description":"Public key corresponding to `privateKey` (PEM format)."}}},"ebay":{"type":"object","description":"eBay REST/Trading API authentication credentials.","properties":{"appId":{"type":"string","description":"eBay application ID from the eBay Developer Program."},"devId":{"type":"string","description":"eBay developer ID from the eBay Developer Program."},"certId":{"type":"string","description":"eBay certificate ID. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"ruName":{"type":"string","description":"eBay Redirect URL Name (RuName) — the auth redirect\ntarget registered in the eBay Developer Program."}}},"amazonmws":{"type":"object","description":"Amazon Marketplace Web Service (MWS) authentication credentials.","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID for MWS API requests."},"secretKey":{"type":"string","description":"AWS secret key. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."}}},"azureserviceprincipal":{"type":"object","description":"Microsoft Entra (Azure AD) service principal credentials. Required\nwhen `provider` is `azureserviceprincipal`. One iClient of this\nprovider can back Azure Data Lake Storage Gen2, Microsoft SQL Server\n(cloud) and Azure Synapse Analytics connections; the connection forms\noffer the certificate method from Microsoft SQL Server connections\nonly.","required":["clientId","tenantId"],"properties":{"authMethod":{"type":"string","enum":["client-secret","certificate"],"default":"client-secret","description":"Which credential the service principal presents. Defaults to\n`client-secret` when omitted. Each method rejects the other\nmethod's credential fields on save. Changing the method on an\nupdate replaces the credential: send the new method's credential\nand drop the old one."},"clientId":{"type":"string","description":"Azure AD application (client) ID."},"clientSecret":{"type":"string","description":"Azure AD client secret. Required when `authMethod` is\n`client-secret` (or omitted). Returned masked as `\"******\"`.\nOn update the stored secret is kept when the field is omitted or\nre-sent as the mask; only a new value replaces it."},"certificate":{"type":"string","writeOnly":true,"description":"PEM bundle (certificate + private key) for certificate auth.\nRequired when `authMethod` is `certificate`; rejected under\n`client-secret`. Maximum 20 KiB of PEM text. Never returned in\nresponses, not even masked. On update the stored PEM is kept when\nthe field is omitted; only a new value replaces it."},"certificatePassword":{"type":"string","description":"Passphrase for an encrypted private key inside `certificate`.\nRequired exactly when the PEM's key is encrypted; rejected when\nit is not. Maximum 256 bytes. Returned masked when set."},"tenantId":{"type":"string","description":"Azure AD tenant (directory) ID."}}},"googleserviceaccount":{"type":"object","description":"Google Cloud service-account credentials. Required when `provider` is\n`googleserviceaccount`. Send the raw JSON key file in\n`serviceAccountJSON`; the server parses out `project_id`,\n`client_email`, and `private_key` and stores them (the private key\nencrypted). Responses return only `clientEmail`.","properties":{"serviceAccountJSON":{"type":"string","writeOnly":true,"description":"Google service-account key file, sent as a JSON string. The save\nreads `project_id`, `client_email`, and a `private_key` that\nincludes its PEM armor (its BEGIN and END PRIVATE KEY lines).\nMissing, empty, or incomplete JSON fails with 422\n`invalid_json_key`. Send the full key on every create and every\nupdate — omitting it or sending `\"******\"` fails the same way."},"clientEmail":{"type":"string","readOnly":true,"description":"Service-account email parsed from the key file — the only field echoed in responses."}}},"awsIam":{"type":"object","description":"AWS IAM cross-account role credentials. Required when `provider` is `awsIam`\n(omitting the object fails with 422 `missing_required_field` \"The awsIam sub-schema is\nrequired\"). Celigo assumes `roleArn` using `externalId` as the trust-policy external ID.\nThe iClient itself saves with `externalId` alone; the connection that references it\nadds its own rules on `roleArn` (see that field). One iClient serves one connection\nfamily — Amazon S3, Amazon Redshift, or the AWS HTTP connectors — because each family\naccepts only roles named with its own prefix.","required":["externalId"],"properties":{"externalId":{"type":"string","minLength":2,"maxLength":1224,"pattern":"^[a-zA-Z0-9+=,.@:/_-]+$","description":"External ID Celigo presents when assuming the role; must match the\n`sts:ExternalId` condition in the role's trust policy. Fixed at creation: a `PUT`\nthat sends a different value keeps the stored one. A value outside the allowed\ncharacter set or length fails with 422 `invalid_field_value`."},"roleArn":{"type":"string","pattern":"^arn:[a-z-]+:iam::\\d{12}:role/[A-Za-z0-9+=,.@_/-]{1,576}$","description":"ARN of the AWS IAM role to assume for cross-account access. Optional on the iClient\n(a malformed ARN fails with 422 `invalid_field_value`), but no connection in IAM-role\nmode can be saved against this iClient until it is set, and each connection family\naccepts only its own role-name prefix: `celigo-file-adaptor-` for Amazon S3,\n`celigo-data-warehouse-adaptor-` for Amazon Redshift, `celigo-http-adaptor-` for the\nAWS HTTP connectors (`auth.type` `awsiam`)."}}},"jwt":{"type":"object","description":"JWT assertion configuration. Used when `enableJWT` is true to\ngenerate a signed JWT for inclusion in OAuth token requests via\n`{{{iClient.jwt.token}}}`.","properties":{"signatureMethod":{"type":"string","enum":["hmac-sha256","hmac-sha384","hmac-sha512","rsa-sha256","rsa-sha384","rsa-sha512","es256","es384","es512","ps256","ps384","ps512"],"description":"Algorithm used to sign the JWT. HMAC methods sign with `secret`;\nRSA/ECDSA/PSS methods sign with `privateKey`."},"payload":{"description":"JWT payload claims. Can be a JSON object or a stringified\nJSON template with Handlebars expressions."},"headers":{"description":"JWT header claims. Can be a JSON object or a stringified\nJSON template with Handlebars expressions."},"privateKey":{"type":"string","description":"Private key for signing the JWT. Returned masked as\n`\"******\"`. Re-send that value on update to keep it; it is not preserved if omitted."},"token":{"type":"string","readOnly":true,"description":"Server-computed signed JWT token. Returned masked as\n`\"******\"` in responses."},"secret":{"type":"string","description":"Shared secret for HMAC-based JWT signing (e.g. HS256).\nReturned masked as `\"******\"`. Re-send that value on update to\nkeep it; it is not preserved if omitted."},"isSecretBase64Encoded":{"type":"boolean","description":"When true, the `secret` value is Base64-encoded."}}}},"if":{"properties":{"provider":{"const":"awsIam"}},"required":["provider"]},"then":{"required":["awsIam"]}},"iClient":{"type":"object","required":["_id","provider","lastModified"],"description":"iClient object as returned by the API. Includes all request fields\nplus server-managed metadata. `name` is optional on create and is\nomitted from GET responses when the iClient was created without\none (the create response echoes it as `null`).","allOf":[{"$ref":"#/components/schemas/IClientBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"$ref":"#/components/schemas/IAResourceResponse"}]},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"deletedAt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Timestamp when the resource was soft-deleted. When null or absent, the resource is active."}},"required":["_id"]},"IAResourceResponse":{"type":"object","description":"Integration app response fields for resources that are part of integration apps","properties":{"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Reference to the specific integration instance that contains this resource.\n\nThis field is only populated for resources that are part of an integration app\ninstallation. It contains the unique identifier (_id) of the integration\nresource that was installed in the account.\n\nThe integration instance represents a specific installed instance of an\nintegration app, with its own configuration, settings, and runtime environment.\n\nThis reference enables:\n- Tracing the resource back to its parent integration instance\n- Permission and access control based on integration ownership\n- Lifecycle management (enabling/disabling, updating, or uninstalling)\n"},"_connectorId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration App (connector) that defines this resource. Present only on resources an\nIntegration App owns. The app locks parts of these documents, and a PUT that changes a\nlocked field answers 200 but keeps the stored value, so read the document back to confirm\na change."}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"403-forbidden":{"description":"Forbidden. The authenticated caller does not have permission to perform this operation.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/iclients":{"post":{"summary":"Create an iClient","description":"Creates a new iClient. The `provider` field is required and\ndetermines which credential sub-object must be populated.","operationId":"createIClient","tags":["iClients"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"iClient created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/iClient"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"403":{"$ref":"#/components/responses/403-forbidden"},"422":{"description":"Unprocessable entity. The body was well-formed but the provider's credential\nsub-object is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get an iClient

> Retrieves a single iClient by ID.

```json
{"openapi":"3.2.0","info":{"title":"iClients","version":"1.0.0"},"tags":[{"name":"iClients","description":"iClients are shared OAuth 2.0 credential stores that hold client\nIDs, secrets, and token-endpoint configuration for a specific\napplication or provider. Multiple connections can reference the\nsame iClient so credentials are managed in one place.\n\nEach iClient targets one `provider` — the provider determines\nwhich credential sub-object (`oauth2`, `netsuite`, `salesforce`,\n`ebay`, `amazonmws`, `azureserviceprincipal`, `googleserviceaccount`,\n`awsIam`) is required.\nSecrets are stored encrypted and returned masked as `\"******\"`.\n\n## iClient schema\n\n{% openapi-schemas spec=\"iclient\" schemas=\"iClient\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"iClient":{"type":"object","required":["_id","provider","lastModified"],"description":"iClient object as returned by the API. Includes all request fields\nplus server-managed metadata. `name` is optional on create and is\nomitted from GET responses when the iClient was created without\none (the create response echoes it as `null`).","allOf":[{"$ref":"#/components/schemas/IClientBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"$ref":"#/components/schemas/IAResourceResponse"}]},"IClientBase":{"type":"object","description":"Writable iClient fields shared by the request and response schemas.","properties":{"name":{"type":"string","description":"Display name for the iClient."},"provider":{"type":"string","description":"Authentication provider that determines which credential fields apply.","enum":["custom_oauth2","netsuite","amazonmws","awsIam","azureserviceprincipal","googleserviceaccount","integrator","salesforce","shopify","ebay-xml","microsoftbusinesscentral","google","azureoauth","squareup","zendesk","docusign","ebay","windowslive","bigcommerce","asana","box","dropbox","clover","servicenow","jobvite","twilio","certify","woocommerce"]},"published":{"type":"boolean","description":"When true, this iClient is published and available for use."},"enableJWT":{"type":"boolean","description":"Enables a JWT assertion as part of the OAuth token request.\nWhen true, `{{{iClient.jwt.token}}}` resolves to the signed\nJWT for use in the token URL request body. Requires the `jwt`\nsub-object to be configured."},"enableIClientReferences":{"type":"boolean","description":"When true, other resources can reference this iClient's fields via Handlebars expressions."},"formType":{"type":"string","enum":["assistant","http"],"description":"UI form type. Set automatically by the UI: `assistant` when\n`_httpConnectorId` is present, `http` otherwise."},"_httpConnectorId":{"type":"string","format":"objectId","description":"HTTP connector backing this iClient's guided setup."},"_httpConnectorApiId":{"type":"string","format":"objectId","description":"HTTP connector API definition linked to this iClient."},"settings":{"type":"object","description":"Connector-specific settings (e.g. region, environment, instance\nURI). Shape varies by connector."},"settingsForm":{"type":"object","description":"Dynamic UI form definition for the settings object."},"oauth2":{"type":"object","description":"OAuth 2.0 configuration. Used when `provider` is `custom_oauth2`\nor any OAuth-based provider.","properties":{"clientId":{"type":"string","description":"OAuth 2.0 client ID from the provider's app registration."},"clientSecret":{"type":"string","description":"OAuth 2.0 client secret. Returned masked as `\"******\"`; re-send that mask\non update to keep the stored secret. Required whenever `oauth2` is sent, on\ncreate and update: omitting it or sending an empty string fails with 422\n`missing_required_field` rather than clearing the secret."},"scope":{"type":"array","items":{"type":"string"},"description":"OAuth 2.0 scopes. The API accepts a string on input but\nalways returns an array in responses."},"scopeDelimiter":{"type":"string","description":"Character separating multiple scopes in a single string.\nDefaults to space per the OAuth 2.0 spec (RFC 6749)."},"redirectUri":{"type":"string","description":"OAuth 2.0 redirect URI registered with the provider."},"grantType":{"type":"string","enum":["authorizecode","password","clientcredentials"],"description":"OAuth 2.0 grant type."},"clientCredentialsLocation":{"type":"string","enum":["basicauthheader","body"],"description":"Where to include client credentials in the token request."},"accessTokenLocation":{"type":"string","enum":["url","header","body"],"description":"Where the access token is included in API requests."},"accessTokenHeaderName":{"type":["string","null"],"description":"Header name for the access token when `accessTokenLocation`\nis `header`. Defaults to `Authorization`."},"accessTokenParamName":{"type":"string","description":"Parameter name when the access token is sent as a\nquery or body parameter."},"accessTokenPath":{"type":"string","description":"JSON path to extract the access token from the token\nendpoint response body."},"refreshTokenPath":{"type":"string","description":"JSON path to extract the refresh token from the token\nendpoint response body."},"scheme":{"type":"string","description":"Authorization scheme prefix (e.g. `Bearer`, `Basic`)."},"validDomainNames":{"type":"array","items":{"type":"string"},"description":"Registrable domains (`domain.com`, `domain.co.uk` — the host with its\nsubdomains removed) of the OAuth URLs this client's credentials are\nsent to: the access token, authorization, and revoke URLs. Before an\nOAuth request leaves integrator.io, the target URL's registrable\ndomain must appear here; a full hostname never matches."},"failPath":{"type":"string","description":"Response body path to check for auth errors. Set only if\nthe API uses a field in the response body (not just HTTP\nstatus) to indicate auth failures."},"failValues":{"type":"array","items":{"type":"string"},"description":"Values at `failPath` that indicate an auth failure."},"failStatusCode":{"type":"number","description":"HTTP status code indicating an auth error, if the provider\nuses something other than 401."},"useNewAuthFailSchema":{"type":"boolean","readOnly":true,"description":"Server-managed flag. Always `true` in current responses."},"failures":{"type":"array","readOnly":true,"description":"Server-computed auth-failure detection rules derived from\n`failPath`, `failValues`, and `failStatusCode`. Present\nonly when those fields are configured.","items":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code triggering auth-failure detection."},"path":{"type":"string","description":"Response body path checked for failure values."},"values":{"type":"array","items":{"type":"string"},"description":"Values at `path` that indicate auth failure."}}}},"pkceCodeChallengeMethod":{"type":["string","null"],"enum":["plain","s256"],"description":"PKCE code challenge method (RFC 7636)."},"useIClientFields":{"type":"boolean","description":"Use legacy iClient-specific fields instead of standard\nOAuth 2.0 fields. For backward compatibility only."},"username":{"type":"string","description":"Username for the password grant type.\n\nRequired when grantType is password."},"password":{"type":"string","description":"Password for the password grant type. Returned masked\nas `\"******\"`. Re-send that value on update to keep it; it is not preserved if omitted."},"auth":{"type":"object","description":"Authorization endpoint configuration.","properties":{"uri":{"type":"string","description":"Authorization endpoint URI."},"queryParameters":{"type":"object","description":"Additional query parameters appended to the authorization\nURL. Stored encrypted (masked as `\"****\"` in responses)."}}},"token":{"type":"object","description":"Token endpoint configuration.","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method for the token request."},"uri":{"type":"string","description":"Token endpoint URI."},"body":{"type":"string","description":"Custom request body template for the token request.\nSupports Handlebars expressions."},"headers":{"description":"Custom HTTP headers for the token request. Can be an\narray of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"refresh":{"type":"object","description":"Refresh token endpoint configuration.","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method for the refresh token request."},"uri":{"type":"string","description":"Refresh token endpoint URI."},"body":{"type":"string","description":"Custom request body template for the refresh request.\nSupports Handlebars expressions."},"headers":{"description":"Custom HTTP headers for the refresh token request.\nCan be an array of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"revoke":{"type":"object","description":"Token revocation endpoint configuration (RFC 7009).","properties":{"uri":{"type":"string","description":"Revocation endpoint URI."},"body":{"type":"string","description":"Custom request body for the revocation request."},"headers":{"description":"Custom HTTP headers for the revocation request.\nCan be an array of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"unencrypted":{"type":"object","description":"Non-sensitive key-value pairs accessible via iClient\nreferences (e.g. email, account ID, role)."},"encrypted":{"type":["object","string"],"description":"Sensitive key-value pairs stored with AES-256 encryption.\nSend an object when writing; API responses mask the whole\nvalue as the string `\"******\"`."}}},"netsuite":{"type":"object","description":"NetSuite token-based authentication credentials.","properties":{"consumerKey":{"type":"string","description":"NetSuite consumer key. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"consumerSecret":{"type":"string","description":"NetSuite consumer secret. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."}}},"salesforce":{"type":"object","description":"Salesforce authentication credentials.","properties":{"clientId":{"type":"string","description":"Salesforce connected app client ID."},"clientSecret":{"type":"string","description":"Salesforce client secret. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"apiToken":{"type":"string","description":"Salesforce security token appended to the password for\nusername-password auth flows."},"privateKey":{"type":"string","description":"Private key for Salesforce JWT bearer token flows (PEM\nformat). Returned masked as `\"******\"`."},"publicKey":{"type":"string","description":"Public key corresponding to `privateKey` (PEM format)."}}},"ebay":{"type":"object","description":"eBay REST/Trading API authentication credentials.","properties":{"appId":{"type":"string","description":"eBay application ID from the eBay Developer Program."},"devId":{"type":"string","description":"eBay developer ID from the eBay Developer Program."},"certId":{"type":"string","description":"eBay certificate ID. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"ruName":{"type":"string","description":"eBay Redirect URL Name (RuName) — the auth redirect\ntarget registered in the eBay Developer Program."}}},"amazonmws":{"type":"object","description":"Amazon Marketplace Web Service (MWS) authentication credentials.","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID for MWS API requests."},"secretKey":{"type":"string","description":"AWS secret key. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."}}},"azureserviceprincipal":{"type":"object","description":"Microsoft Entra (Azure AD) service principal credentials. Required\nwhen `provider` is `azureserviceprincipal`. One iClient of this\nprovider can back Azure Data Lake Storage Gen2, Microsoft SQL Server\n(cloud) and Azure Synapse Analytics connections; the connection forms\noffer the certificate method from Microsoft SQL Server connections\nonly.","required":["clientId","tenantId"],"properties":{"authMethod":{"type":"string","enum":["client-secret","certificate"],"default":"client-secret","description":"Which credential the service principal presents. Defaults to\n`client-secret` when omitted. Each method rejects the other\nmethod's credential fields on save. Changing the method on an\nupdate replaces the credential: send the new method's credential\nand drop the old one."},"clientId":{"type":"string","description":"Azure AD application (client) ID."},"clientSecret":{"type":"string","description":"Azure AD client secret. Required when `authMethod` is\n`client-secret` (or omitted). Returned masked as `\"******\"`.\nOn update the stored secret is kept when the field is omitted or\nre-sent as the mask; only a new value replaces it."},"certificate":{"type":"string","writeOnly":true,"description":"PEM bundle (certificate + private key) for certificate auth.\nRequired when `authMethod` is `certificate`; rejected under\n`client-secret`. Maximum 20 KiB of PEM text. Never returned in\nresponses, not even masked. On update the stored PEM is kept when\nthe field is omitted; only a new value replaces it."},"certificatePassword":{"type":"string","description":"Passphrase for an encrypted private key inside `certificate`.\nRequired exactly when the PEM's key is encrypted; rejected when\nit is not. Maximum 256 bytes. Returned masked when set."},"tenantId":{"type":"string","description":"Azure AD tenant (directory) ID."}}},"googleserviceaccount":{"type":"object","description":"Google Cloud service-account credentials. Required when `provider` is\n`googleserviceaccount`. Send the raw JSON key file in\n`serviceAccountJSON`; the server parses out `project_id`,\n`client_email`, and `private_key` and stores them (the private key\nencrypted). Responses return only `clientEmail`.","properties":{"serviceAccountJSON":{"type":"string","writeOnly":true,"description":"Google service-account key file, sent as a JSON string. The save\nreads `project_id`, `client_email`, and a `private_key` that\nincludes its PEM armor (its BEGIN and END PRIVATE KEY lines).\nMissing, empty, or incomplete JSON fails with 422\n`invalid_json_key`. Send the full key on every create and every\nupdate — omitting it or sending `\"******\"` fails the same way."},"clientEmail":{"type":"string","readOnly":true,"description":"Service-account email parsed from the key file — the only field echoed in responses."}}},"awsIam":{"type":"object","description":"AWS IAM cross-account role credentials. Required when `provider` is `awsIam`\n(omitting the object fails with 422 `missing_required_field` \"The awsIam sub-schema is\nrequired\"). Celigo assumes `roleArn` using `externalId` as the trust-policy external ID.\nThe iClient itself saves with `externalId` alone; the connection that references it\nadds its own rules on `roleArn` (see that field). One iClient serves one connection\nfamily — Amazon S3, Amazon Redshift, or the AWS HTTP connectors — because each family\naccepts only roles named with its own prefix.","required":["externalId"],"properties":{"externalId":{"type":"string","minLength":2,"maxLength":1224,"pattern":"^[a-zA-Z0-9+=,.@:/_-]+$","description":"External ID Celigo presents when assuming the role; must match the\n`sts:ExternalId` condition in the role's trust policy. Fixed at creation: a `PUT`\nthat sends a different value keeps the stored one. A value outside the allowed\ncharacter set or length fails with 422 `invalid_field_value`."},"roleArn":{"type":"string","pattern":"^arn:[a-z-]+:iam::\\d{12}:role/[A-Za-z0-9+=,.@_/-]{1,576}$","description":"ARN of the AWS IAM role to assume for cross-account access. Optional on the iClient\n(a malformed ARN fails with 422 `invalid_field_value`), but no connection in IAM-role\nmode can be saved against this iClient until it is set, and each connection family\naccepts only its own role-name prefix: `celigo-file-adaptor-` for Amazon S3,\n`celigo-data-warehouse-adaptor-` for Amazon Redshift, `celigo-http-adaptor-` for the\nAWS HTTP connectors (`auth.type` `awsiam`)."}}},"jwt":{"type":"object","description":"JWT assertion configuration. Used when `enableJWT` is true to\ngenerate a signed JWT for inclusion in OAuth token requests via\n`{{{iClient.jwt.token}}}`.","properties":{"signatureMethod":{"type":"string","enum":["hmac-sha256","hmac-sha384","hmac-sha512","rsa-sha256","rsa-sha384","rsa-sha512","es256","es384","es512","ps256","ps384","ps512"],"description":"Algorithm used to sign the JWT. HMAC methods sign with `secret`;\nRSA/ECDSA/PSS methods sign with `privateKey`."},"payload":{"description":"JWT payload claims. Can be a JSON object or a stringified\nJSON template with Handlebars expressions."},"headers":{"description":"JWT header claims. Can be a JSON object or a stringified\nJSON template with Handlebars expressions."},"privateKey":{"type":"string","description":"Private key for signing the JWT. Returned masked as\n`\"******\"`. Re-send that value on update to keep it; it is not preserved if omitted."},"token":{"type":"string","readOnly":true,"description":"Server-computed signed JWT token. Returned masked as\n`\"******\"` in responses."},"secret":{"type":"string","description":"Shared secret for HMAC-based JWT signing (e.g. HS256).\nReturned masked as `\"******\"`. Re-send that value on update to\nkeep it; it is not preserved if omitted."},"isSecretBase64Encoded":{"type":"boolean","description":"When true, the `secret` value is Base64-encoded."}}}},"if":{"properties":{"provider":{"const":"awsIam"}},"required":["provider"]},"then":{"required":["awsIam"]}},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"deletedAt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Timestamp when the resource was soft-deleted. When null or absent, the resource is active."}},"required":["_id"]},"IAResourceResponse":{"type":"object","description":"Integration app response fields for resources that are part of integration apps","properties":{"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Reference to the specific integration instance that contains this resource.\n\nThis field is only populated for resources that are part of an integration app\ninstallation. It contains the unique identifier (_id) of the integration\nresource that was installed in the account.\n\nThe integration instance represents a specific installed instance of an\nintegration app, with its own configuration, settings, and runtime environment.\n\nThis reference enables:\n- Tracing the resource back to its parent integration instance\n- Permission and access control based on integration ownership\n- Lifecycle management (enabling/disabling, updating, or uninstalling)\n"},"_connectorId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration App (connector) that defines this resource. Present only on resources an\nIntegration App owns. The app locks parts of these documents, and a PUT that changes a\nlocked field answers 200 but keeps the stored value, so read the document back to confirm\na change."}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/iclients/{_id}":{"get":{"summary":"Get an iClient","description":"Retrieves a single iClient by ID.","operationId":"getIClientById","tags":["iClients"],"parameters":[{"in":"path","name":"_id","required":true,"schema":{"type":"string","format":"objectId"},"description":"iClient ID."}],"responses":{"200":{"description":"iClient object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/iClient"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Update an iClient

> Replaces an existing iClient; create one with \`POST /v1/iclients\`. All\
> mutable fields must be provided — omitted fields are reset to defaults.\
> Secrets returned as \`"\*\*\*\*\*\*"\` can be\
> sent back as-is to keep the existing value, except a Google service\
> account: every update must include the full JSON key. An Azure\
> service principal keeps its stored \`clientSecret\` or \`certificate\`\
> when the field is omitted — only a new value replaces it, and\
> \`certificate\` is never returned. A connection keeps a secret re-sent\
> as the mask the same way (\`PUT /v1/connections/{\_id}\`).

```json
{"openapi":"3.2.0","info":{"title":"iClients","version":"1.0.0"},"tags":[{"name":"iClients","description":"iClients are shared OAuth 2.0 credential stores that hold client\nIDs, secrets, and token-endpoint configuration for a specific\napplication or provider. Multiple connections can reference the\nsame iClient so credentials are managed in one place.\n\nEach iClient targets one `provider` — the provider determines\nwhich credential sub-object (`oauth2`, `netsuite`, `salesforce`,\n`ebay`, `amazonmws`, `azureserviceprincipal`, `googleserviceaccount`,\n`awsIam`) is required.\nSecrets are stored encrypted and returned masked as `\"******\"`.\n\n## iClient schema\n\n{% openapi-schemas spec=\"iclient\" schemas=\"iClient\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"iClient configuration. The shape varies by `provider` — each provider\nrequires its own credential sub-object (`oauth2`, `netsuite`,\n`salesforce`, `ebay`, `amazonmws`, `azureserviceprincipal`,\n`googleserviceaccount`, `awsIam`).\nFor `custom_oauth2`, credentials go in the `oauth2` sub-object.\nSecrets (`clientSecret`, `privateKey`, and so on) come back masked\nas `\"******\"`. Re-send that mask on update to keep the stored\nsecret; omitting it does not. Two providers differ. A Google\nservice account: `serviceAccountJSON` is not returned, and every\nupdate must send the full key — the mask or an omission fails with\n422 `invalid_json_key`. An Azure service principal: the stored\n`clientSecret` or `certificate` is kept when its field is omitted\non update, and only a new value replaces it (`certificate` is never\nreturned, not even masked).","required":["provider"],"allOf":[{"$ref":"#/components/schemas/IClientBase"}]},"IClientBase":{"type":"object","description":"Writable iClient fields shared by the request and response schemas.","properties":{"name":{"type":"string","description":"Display name for the iClient."},"provider":{"type":"string","description":"Authentication provider that determines which credential fields apply.","enum":["custom_oauth2","netsuite","amazonmws","awsIam","azureserviceprincipal","googleserviceaccount","integrator","salesforce","shopify","ebay-xml","microsoftbusinesscentral","google","azureoauth","squareup","zendesk","docusign","ebay","windowslive","bigcommerce","asana","box","dropbox","clover","servicenow","jobvite","twilio","certify","woocommerce"]},"published":{"type":"boolean","description":"When true, this iClient is published and available for use."},"enableJWT":{"type":"boolean","description":"Enables a JWT assertion as part of the OAuth token request.\nWhen true, `{{{iClient.jwt.token}}}` resolves to the signed\nJWT for use in the token URL request body. Requires the `jwt`\nsub-object to be configured."},"enableIClientReferences":{"type":"boolean","description":"When true, other resources can reference this iClient's fields via Handlebars expressions."},"formType":{"type":"string","enum":["assistant","http"],"description":"UI form type. Set automatically by the UI: `assistant` when\n`_httpConnectorId` is present, `http` otherwise."},"_httpConnectorId":{"type":"string","format":"objectId","description":"HTTP connector backing this iClient's guided setup."},"_httpConnectorApiId":{"type":"string","format":"objectId","description":"HTTP connector API definition linked to this iClient."},"settings":{"type":"object","description":"Connector-specific settings (e.g. region, environment, instance\nURI). Shape varies by connector."},"settingsForm":{"type":"object","description":"Dynamic UI form definition for the settings object."},"oauth2":{"type":"object","description":"OAuth 2.0 configuration. Used when `provider` is `custom_oauth2`\nor any OAuth-based provider.","properties":{"clientId":{"type":"string","description":"OAuth 2.0 client ID from the provider's app registration."},"clientSecret":{"type":"string","description":"OAuth 2.0 client secret. Returned masked as `\"******\"`; re-send that mask\non update to keep the stored secret. Required whenever `oauth2` is sent, on\ncreate and update: omitting it or sending an empty string fails with 422\n`missing_required_field` rather than clearing the secret."},"scope":{"type":"array","items":{"type":"string"},"description":"OAuth 2.0 scopes. The API accepts a string on input but\nalways returns an array in responses."},"scopeDelimiter":{"type":"string","description":"Character separating multiple scopes in a single string.\nDefaults to space per the OAuth 2.0 spec (RFC 6749)."},"redirectUri":{"type":"string","description":"OAuth 2.0 redirect URI registered with the provider."},"grantType":{"type":"string","enum":["authorizecode","password","clientcredentials"],"description":"OAuth 2.0 grant type."},"clientCredentialsLocation":{"type":"string","enum":["basicauthheader","body"],"description":"Where to include client credentials in the token request."},"accessTokenLocation":{"type":"string","enum":["url","header","body"],"description":"Where the access token is included in API requests."},"accessTokenHeaderName":{"type":["string","null"],"description":"Header name for the access token when `accessTokenLocation`\nis `header`. Defaults to `Authorization`."},"accessTokenParamName":{"type":"string","description":"Parameter name when the access token is sent as a\nquery or body parameter."},"accessTokenPath":{"type":"string","description":"JSON path to extract the access token from the token\nendpoint response body."},"refreshTokenPath":{"type":"string","description":"JSON path to extract the refresh token from the token\nendpoint response body."},"scheme":{"type":"string","description":"Authorization scheme prefix (e.g. `Bearer`, `Basic`)."},"validDomainNames":{"type":"array","items":{"type":"string"},"description":"Registrable domains (`domain.com`, `domain.co.uk` — the host with its\nsubdomains removed) of the OAuth URLs this client's credentials are\nsent to: the access token, authorization, and revoke URLs. Before an\nOAuth request leaves integrator.io, the target URL's registrable\ndomain must appear here; a full hostname never matches."},"failPath":{"type":"string","description":"Response body path to check for auth errors. Set only if\nthe API uses a field in the response body (not just HTTP\nstatus) to indicate auth failures."},"failValues":{"type":"array","items":{"type":"string"},"description":"Values at `failPath` that indicate an auth failure."},"failStatusCode":{"type":"number","description":"HTTP status code indicating an auth error, if the provider\nuses something other than 401."},"useNewAuthFailSchema":{"type":"boolean","readOnly":true,"description":"Server-managed flag. Always `true` in current responses."},"failures":{"type":"array","readOnly":true,"description":"Server-computed auth-failure detection rules derived from\n`failPath`, `failValues`, and `failStatusCode`. Present\nonly when those fields are configured.","items":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code triggering auth-failure detection."},"path":{"type":"string","description":"Response body path checked for failure values."},"values":{"type":"array","items":{"type":"string"},"description":"Values at `path` that indicate auth failure."}}}},"pkceCodeChallengeMethod":{"type":["string","null"],"enum":["plain","s256"],"description":"PKCE code challenge method (RFC 7636)."},"useIClientFields":{"type":"boolean","description":"Use legacy iClient-specific fields instead of standard\nOAuth 2.0 fields. For backward compatibility only."},"username":{"type":"string","description":"Username for the password grant type.\n\nRequired when grantType is password."},"password":{"type":"string","description":"Password for the password grant type. Returned masked\nas `\"******\"`. Re-send that value on update to keep it; it is not preserved if omitted."},"auth":{"type":"object","description":"Authorization endpoint configuration.","properties":{"uri":{"type":"string","description":"Authorization endpoint URI."},"queryParameters":{"type":"object","description":"Additional query parameters appended to the authorization\nURL. Stored encrypted (masked as `\"****\"` in responses)."}}},"token":{"type":"object","description":"Token endpoint configuration.","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method for the token request."},"uri":{"type":"string","description":"Token endpoint URI."},"body":{"type":"string","description":"Custom request body template for the token request.\nSupports Handlebars expressions."},"headers":{"description":"Custom HTTP headers for the token request. Can be an\narray of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"refresh":{"type":"object","description":"Refresh token endpoint configuration.","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method for the refresh token request."},"uri":{"type":"string","description":"Refresh token endpoint URI."},"body":{"type":"string","description":"Custom request body template for the refresh request.\nSupports Handlebars expressions."},"headers":{"description":"Custom HTTP headers for the refresh token request.\nCan be an array of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"revoke":{"type":"object","description":"Token revocation endpoint configuration (RFC 7009).","properties":{"uri":{"type":"string","description":"Revocation endpoint URI."},"body":{"type":"string","description":"Custom request body for the revocation request."},"headers":{"description":"Custom HTTP headers for the revocation request.\nCan be an array of `{name, value}` objects or a string.","oneOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the HTTP header to send."},"value":{"type":"string","description":"Value of the HTTP header to send."}}}},{"type":"string"},{"type":"null"}]}}},"unencrypted":{"type":"object","description":"Non-sensitive key-value pairs accessible via iClient\nreferences (e.g. email, account ID, role)."},"encrypted":{"type":["object","string"],"description":"Sensitive key-value pairs stored with AES-256 encryption.\nSend an object when writing; API responses mask the whole\nvalue as the string `\"******\"`."}}},"netsuite":{"type":"object","description":"NetSuite token-based authentication credentials.","properties":{"consumerKey":{"type":"string","description":"NetSuite consumer key. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"consumerSecret":{"type":"string","description":"NetSuite consumer secret. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."}}},"salesforce":{"type":"object","description":"Salesforce authentication credentials.","properties":{"clientId":{"type":"string","description":"Salesforce connected app client ID."},"clientSecret":{"type":"string","description":"Salesforce client secret. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"apiToken":{"type":"string","description":"Salesforce security token appended to the password for\nusername-password auth flows."},"privateKey":{"type":"string","description":"Private key for Salesforce JWT bearer token flows (PEM\nformat). Returned masked as `\"******\"`."},"publicKey":{"type":"string","description":"Public key corresponding to `privateKey` (PEM format)."}}},"ebay":{"type":"object","description":"eBay REST/Trading API authentication credentials.","properties":{"appId":{"type":"string","description":"eBay application ID from the eBay Developer Program."},"devId":{"type":"string","description":"eBay developer ID from the eBay Developer Program."},"certId":{"type":"string","description":"eBay certificate ID. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"ruName":{"type":"string","description":"eBay Redirect URL Name (RuName) — the auth redirect\ntarget registered in the eBay Developer Program."}}},"amazonmws":{"type":"object","description":"Amazon Marketplace Web Service (MWS) authentication credentials.","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID for MWS API requests."},"secretKey":{"type":"string","description":"AWS secret key. Returned masked as `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."}}},"azureserviceprincipal":{"type":"object","description":"Microsoft Entra (Azure AD) service principal credentials. Required\nwhen `provider` is `azureserviceprincipal`. One iClient of this\nprovider can back Azure Data Lake Storage Gen2, Microsoft SQL Server\n(cloud) and Azure Synapse Analytics connections; the connection forms\noffer the certificate method from Microsoft SQL Server connections\nonly.","required":["clientId","tenantId"],"properties":{"authMethod":{"type":"string","enum":["client-secret","certificate"],"default":"client-secret","description":"Which credential the service principal presents. Defaults to\n`client-secret` when omitted. Each method rejects the other\nmethod's credential fields on save. Changing the method on an\nupdate replaces the credential: send the new method's credential\nand drop the old one."},"clientId":{"type":"string","description":"Azure AD application (client) ID."},"clientSecret":{"type":"string","description":"Azure AD client secret. Required when `authMethod` is\n`client-secret` (or omitted). Returned masked as `\"******\"`.\nOn update the stored secret is kept when the field is omitted or\nre-sent as the mask; only a new value replaces it."},"certificate":{"type":"string","writeOnly":true,"description":"PEM bundle (certificate + private key) for certificate auth.\nRequired when `authMethod` is `certificate`; rejected under\n`client-secret`. Maximum 20 KiB of PEM text. Never returned in\nresponses, not even masked. On update the stored PEM is kept when\nthe field is omitted; only a new value replaces it."},"certificatePassword":{"type":"string","description":"Passphrase for an encrypted private key inside `certificate`.\nRequired exactly when the PEM's key is encrypted; rejected when\nit is not. Maximum 256 bytes. Returned masked when set."},"tenantId":{"type":"string","description":"Azure AD tenant (directory) ID."}}},"googleserviceaccount":{"type":"object","description":"Google Cloud service-account credentials. Required when `provider` is\n`googleserviceaccount`. Send the raw JSON key file in\n`serviceAccountJSON`; the server parses out `project_id`,\n`client_email`, and `private_key` and stores them (the private key\nencrypted). Responses return only `clientEmail`.","properties":{"serviceAccountJSON":{"type":"string","writeOnly":true,"description":"Google service-account key file, sent as a JSON string. The save\nreads `project_id`, `client_email`, and a `private_key` that\nincludes its PEM armor (its BEGIN and END PRIVATE KEY lines).\nMissing, empty, or incomplete JSON fails with 422\n`invalid_json_key`. Send the full key on every create and every\nupdate — omitting it or sending `\"******\"` fails the same way."},"clientEmail":{"type":"string","readOnly":true,"description":"Service-account email parsed from the key file — the only field echoed in responses."}}},"awsIam":{"type":"object","description":"AWS IAM cross-account role credentials. Required when `provider` is `awsIam`\n(omitting the object fails with 422 `missing_required_field` \"The awsIam sub-schema is\nrequired\"). Celigo assumes `roleArn` using `externalId` as the trust-policy external ID.\nThe iClient itself saves with `externalId` alone; the connection that references it\nadds its own rules on `roleArn` (see that field). One iClient serves one connection\nfamily — Amazon S3, Amazon Redshift, or the AWS HTTP connectors — because each family\naccepts only roles named with its own prefix.","required":["externalId"],"properties":{"externalId":{"type":"string","minLength":2,"maxLength":1224,"pattern":"^[a-zA-Z0-9+=,.@:/_-]+$","description":"External ID Celigo presents when assuming the role; must match the\n`sts:ExternalId` condition in the role's trust policy. Fixed at creation: a `PUT`\nthat sends a different value keeps the stored one. A value outside the allowed\ncharacter set or length fails with 422 `invalid_field_value`."},"roleArn":{"type":"string","pattern":"^arn:[a-z-]+:iam::\\d{12}:role/[A-Za-z0-9+=,.@_/-]{1,576}$","description":"ARN of the AWS IAM role to assume for cross-account access. Optional on the iClient\n(a malformed ARN fails with 422 `invalid_field_value`), but no connection in IAM-role\nmode can be saved against this iClient until it is set, and each connection family\naccepts only its own role-name prefix: `celigo-file-adaptor-` for Amazon S3,\n`celigo-data-warehouse-adaptor-` for Amazon Redshift, `celigo-http-adaptor-` for the\nAWS HTTP connectors (`auth.type` `awsiam`)."}}},"jwt":{"type":"object","description":"JWT assertion configuration. Used when `enableJWT` is true to\ngenerate a signed JWT for inclusion in OAuth token requests via\n`{{{iClient.jwt.token}}}`.","properties":{"signatureMethod":{"type":"string","enum":["hmac-sha256","hmac-sha384","hmac-sha512","rsa-sha256","rsa-sha384","rsa-sha512","es256","es384","es512","ps256","ps384","ps512"],"description":"Algorithm used to sign the JWT. HMAC methods sign with `secret`;\nRSA/ECDSA/PSS methods sign with `privateKey`."},"payload":{"description":"JWT payload claims. Can be a JSON object or a stringified\nJSON template with Handlebars expressions."},"headers":{"description":"JWT header claims. Can be a JSON object or a stringified\nJSON template with Handlebars expressions."},"privateKey":{"type":"string","description":"Private key for signing the JWT. Returned masked as\n`\"******\"`. Re-send that value on update to keep it; it is not preserved if omitted."},"token":{"type":"string","readOnly":true,"description":"Server-computed signed JWT token. Returned masked as\n`\"******\"` in responses."},"secret":{"type":"string","description":"Shared secret for HMAC-based JWT signing (e.g. HS256).\nReturned masked as `\"******\"`. Re-send that value on update to\nkeep it; it is not preserved if omitted."},"isSecretBase64Encoded":{"type":"boolean","description":"When true, the `secret` value is Base64-encoded."}}}},"if":{"properties":{"provider":{"const":"awsIam"}},"required":["provider"]},"then":{"required":["awsIam"]}},"iClient":{"type":"object","required":["_id","provider","lastModified"],"description":"iClient object as returned by the API. Includes all request fields\nplus server-managed metadata. `name` is optional on create and is\nomitted from GET responses when the iClient was created without\none (the create response echoes it as `null`).","allOf":[{"$ref":"#/components/schemas/IClientBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"$ref":"#/components/schemas/IAResourceResponse"}]},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"deletedAt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Timestamp when the resource was soft-deleted. When null or absent, the resource is active."}},"required":["_id"]},"IAResourceResponse":{"type":"object","description":"Integration app response fields for resources that are part of integration apps","properties":{"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Reference to the specific integration instance that contains this resource.\n\nThis field is only populated for resources that are part of an integration app\ninstallation. It contains the unique identifier (_id) of the integration\nresource that was installed in the account.\n\nThe integration instance represents a specific installed instance of an\nintegration app, with its own configuration, settings, and runtime environment.\n\nThis reference enables:\n- Tracing the resource back to its parent integration instance\n- Permission and access control based on integration ownership\n- Lifecycle management (enabling/disabling, updating, or uninstalling)\n"},"_connectorId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration App (connector) that defines this resource. Present only on resources an\nIntegration App owns. The app locks parts of these documents, and a PUT that changes a\nlocked field answers 200 but keeps the stored value, so read the document back to confirm\na change."}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/iclients/{_id}":{"put":{"summary":"Update an iClient","description":"Replaces an existing iClient; create one with `POST /v1/iclients`. All\nmutable fields must be provided — omitted fields are reset to defaults.\nSecrets returned as `\"******\"` can be\nsent back as-is to keep the existing value, except a Google service\naccount: every update must include the full JSON key. An Azure\nservice principal keeps its stored `clientSecret` or `certificate`\nwhen the field is omitted — only a new value replaces it, and\n`certificate` is never returned. A connection keeps a secret re-sent\nas the mask the same way (`PUT /v1/connections/{_id}`).","operationId":"updateIClient","tags":["iClients"],"parameters":[{"in":"path","name":"_id","required":true,"schema":{"type":"string","format":"objectId"},"description":"iClient ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"Updated iClient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/iClient"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"description":"Unprocessable entity. The body was well-formed but a credential\nfield failed validation. A Google service account update without\nthe full JSON key is rejected here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Delete an iClient

> Permanently deletes an iClient. Blocked while any connection references\
> it, including a deleted connection still in the recycle bin: purge that\
> connection with \`DELETE /v1/recycleBinTTL/connections/{\_id}\` first.\
> \`GET /v1/iclients/{\_id}/dependencies\` doesn't list a binned connection,\
> so an empty dependency list doesn't mean the delete will succeed.

```json
{"openapi":"3.2.0","info":{"title":"iClients","version":"1.0.0"},"tags":[{"name":"iClients","description":"iClients are shared OAuth 2.0 credential stores that hold client\nIDs, secrets, and token-endpoint configuration for a specific\napplication or provider. Multiple connections can reference the\nsame iClient so credentials are managed in one place.\n\nEach iClient targets one `provider` — the provider determines\nwhich credential sub-object (`oauth2`, `netsuite`, `salesforce`,\n`ebay`, `amazonmws`, `azureserviceprincipal`, `googleserviceaccount`,\n`awsIam`) is required.\nSecrets are stored encrypted and returned masked as `\"******\"`.\n\n## iClient schema\n\n{% openapi-schemas spec=\"iclient\" schemas=\"iClient\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/iclients/{_id}":{"delete":{"summary":"Delete an iClient","description":"Permanently deletes an iClient. Blocked while any connection references\nit, including a deleted connection still in the recycle bin: purge that\nconnection with `DELETE /v1/recycleBinTTL/connections/{_id}` first.\n`GET /v1/iclients/{_id}/dependencies` doesn't list a binned connection,\nso an empty dependency list doesn't mean the delete will succeed.","operationId":"deleteIClient","tags":["iClients"],"parameters":[{"in":"path","name":"_id","required":true,"schema":{"type":"string","format":"objectId"},"description":"iClient ID."}],"responses":{"204":{"description":"iClient deleted (no response body)."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"description":"A connection still references the iClient. A deleted connection in the\nrecycle bin counts until it is purged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Patch an iClient

> Partially updates an iClient using JSON Patch (RFC 6902). Only\
> \`/oauth2/failPath\` is patchable; use PUT for other field changes.

```json
{"openapi":"3.2.0","info":{"title":"iClients","version":"1.0.0"},"tags":[{"name":"iClients","description":"iClients are shared OAuth 2.0 credential stores that hold client\nIDs, secrets, and token-endpoint configuration for a specific\napplication or provider. Multiple connections can reference the\nsame iClient so credentials are managed in one place.\n\nEach iClient targets one `provider` — the provider determines\nwhich credential sub-object (`oauth2`, `netsuite`, `salesforce`,\n`ebay`, `amazonmws`, `azureserviceprincipal`, `googleserviceaccount`,\n`awsIam`) is required.\nSecrets are stored encrypted and returned masked as `\"******\"`.\n\n## iClient schema\n\n{% openapi-schemas spec=\"iclient\" schemas=\"iClient\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/iclients/{_id}":{"patch":{"summary":"Patch an iClient","description":"Partially updates an iClient using JSON Patch (RFC 6902). Only\n`/oauth2/failPath` is patchable; use PUT for other field changes.","operationId":"patchIClient","tags":["iClients"],"parameters":[{"in":"path","name":"_id","required":true,"schema":{"type":"string","format":"objectId"},"description":"iClient ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["op","path"],"properties":{"op":{"type":"string","enum":["replace","add","remove"],"description":"JSON Patch operation."},"path":{"type":"string","enum":["/oauth2/failPath"],"description":"JSON Pointer to modify. Only `/oauth2/failPath` is\nwhitelisted."},"value":{"type":"string","description":"New value. Required for `replace` and `add`;\nomit for `remove`."}}}}}}},"responses":{"204":{"description":"Patch applied (no response body)."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"description":"Patch rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## List dependencies of an iClient

> Returns the set of resources that depend on the specified resource.\
> The response is an object whose keys are dependent-resource types\
> (e.g. \`flows\`, \`imports\`) and whose values are arrays of dependency\
> entries. Returns \`{}\` when no dependents exist, including for\
> well-formatted but nonexistent IDs.

```json
{"openapi":"3.2.0","info":{"title":"iClients","version":"1.0.0"},"tags":[{"name":"iClients","description":"iClients are shared OAuth 2.0 credential stores that hold client\nIDs, secrets, and token-endpoint configuration for a specific\napplication or provider. Multiple connections can reference the\nsame iClient so credentials are managed in one place.\n\nEach iClient targets one `provider` — the provider determines\nwhich credential sub-object (`oauth2`, `netsuite`, `salesforce`,\n`ebay`, `amazonmws`, `azureserviceprincipal`, `googleserviceaccount`,\n`awsIam`) is required.\nSecrets are stored encrypted and returned masked as `\"******\"`.\n\n## iClient schema\n\n{% openapi-schemas spec=\"iclient\" schemas=\"iClient\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"DependencyResponse":{"type":"object","description":"Map of dependent-resource types to arrays of dependency entries.\nKeys are plural resource type strings (e.g. `flows`, `imports`,\n`connections`). An empty object `{}` means no dependents.\n","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/DependencyEntry"}}},"DependencyEntry":{"type":"object","description":"A single resource that depends on the queried resource.","properties":{"id":{"type":"string","description":"Unique identifier of the dependent resource."},"name":{"type":"string","description":"Display name of the dependent resource."},"type":{"type":"string","description":"Sub-type of the dependent resource when its collection distinguishes one, such as\n`stream` for a listener export. Only present for resource types that carry a `type`."},"paths":{"type":"array","description":"Dot-notation paths within the dependent resource that reference\nthe target resource. `[*]` denotes array elements.","items":{"type":"string"}},"accessLevel":{"type":"string","description":"The caller's access level on the dependent resource."},"dependencyIds":{"type":"object","description":"Map of resource types to arrays of IDs that this dependent\nresource references on the target. Keys are singular or plural\nresource type strings; values are arrays of ID strings.","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["id","name","paths","accessLevel","dependencyIds"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/iclients/{_id}/dependencies":{"get":{"operationId":"listIClientDependencies","tags":["iClients"],"summary":"List dependencies of an iClient","description":"Returns the set of resources that depend on the specified resource.\nThe response is an object whose keys are dependent-resource types\n(e.g. `flows`, `imports`) and whose values are arrays of dependency\nentries. Returns `{}` when no dependents exist, including for\nwell-formatted but nonexistent IDs.","parameters":[{"name":"_id","in":"path","required":true,"description":"Resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Dependency map. Keys are resource-type strings; values are arrays\nof dependency entries. Returns `{}` when no dependents exist.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependencyResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```