> 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/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`) 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 `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"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":"Domain names used to validate OAuth URLs. Provide each\nunique domain once (no scheme, no path)."},"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":"Azure AD service principal credentials. Required when `provider`\nis `azureserviceprincipal`.","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."},"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 `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"certificate":{"type":"string","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. Returned masked."},"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."},"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":"Full Google service-account key file as a JSON string. Must parse\nas JSON and contain `project_id`, `client_email`, and a valid PEM\n`private_key` — otherwise the save fails with\nICLIENT_GOOGLESERVICEACCOUNT_INVALID_JSON_KEY (or _INVALID_PEM\nwhen only the key material is malformed). On update, omitting it\n(or sending the mask) keeps the stored credentials."},"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`.\nCeligo assumes `roleArn` using `externalId` as the trust-policy external ID.","required":["externalId"],"properties":{"externalId":{"type":"string","description":"External ID Celigo presents when assuming the role; must match the\n`sts:ExternalId` condition in the role's trust policy."},"roleArn":{"type":"string","description":"ARN of the AWS IAM role to assume for cross-account access."}}},"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."}}}}},"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":"Reference to the integration app that defines this resource.\n\nThis field is only populated for resources that are part of an integration app.\nIt contains the unique identifier (_id) of the integration app (connector)\nthat defines the structure, behavior, and templates for this resource.\n\nThe integration app is the published template that can be installed\nmultiple times across different accounts, with each installation creating\na separate integration instance (referenced by _integrationId).\n\nThis reference enables:\n- Identifying the source integration app for this resource\n- Determining which template version is being used\n- Linking to documentation, support, and marketplace information\n"}}}}}}
```

## 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`) 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 `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"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":"Domain names used to validate OAuth URLs. Provide each\nunique domain once (no scheme, no path)."},"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":"Azure AD service principal credentials. Required when `provider`\nis `azureserviceprincipal`.","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."},"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 `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"certificate":{"type":"string","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. Returned masked."},"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."},"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":"Full Google service-account key file as a JSON string. Must parse\nas JSON and contain `project_id`, `client_email`, and a valid PEM\n`private_key` — otherwise the save fails with\nICLIENT_GOOGLESERVICEACCOUNT_INVALID_JSON_KEY (or _INVALID_PEM\nwhen only the key material is malformed). On update, omitting it\n(or sending the mask) keeps the stored credentials."},"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`.\nCeligo assumes `roleArn` using `externalId` as the trust-policy external ID.","required":["externalId"],"properties":{"externalId":{"type":"string","description":"External ID Celigo presents when assuming the role; must match the\n`sts:ExternalId` condition in the role's trust policy."},"roleArn":{"type":"string","description":"ARN of the AWS IAM role to assume for cross-account access."}}},"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."}}}}},"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":"Reference to the integration app that defines this resource.\n\nThis field is only populated for resources that are part of an integration app.\nIt contains the unique identifier (_id) of the integration app (connector)\nthat defines the structure, behavior, and templates for this resource.\n\nThe integration app is the published template that can be installed\nmultiple times across different accounts, with each installation creating\na separate integration instance (referenced by _integrationId).\n\nThis reference enables:\n- Identifying the source integration app for this resource\n- Determining which template version is being used\n- Linking to documentation, support, and marketplace information\n"}}}},"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`) 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`).\nFor `custom_oauth2`, credentials go in the `oauth2` sub-object.\nSecrets (`clientSecret`, `privateKey`, etc.) are returned masked\nas `\"******\"`. On update, re-send that masked value to keep the\nexisting secret; secrets are not preserved if omitted.","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 `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"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":"Domain names used to validate OAuth URLs. Provide each\nunique domain once (no scheme, no path)."},"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":"Azure AD service principal credentials. Required when `provider`\nis `azureserviceprincipal`.","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."},"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 `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"certificate":{"type":"string","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. Returned masked."},"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."},"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":"Full Google service-account key file as a JSON string. Must parse\nas JSON and contain `project_id`, `client_email`, and a valid PEM\n`private_key` — otherwise the save fails with\nICLIENT_GOOGLESERVICEACCOUNT_INVALID_JSON_KEY (or _INVALID_PEM\nwhen only the key material is malformed). On update, omitting it\n(or sending the mask) keeps the stored credentials."},"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`.\nCeligo assumes `roleArn` using `externalId` as the trust-policy external ID.","required":["externalId"],"properties":{"externalId":{"type":"string","description":"External ID Celigo presents when assuming the role; must match the\n`sts:ExternalId` condition in the role's trust policy."},"roleArn":{"type":"string","description":"ARN of the AWS IAM role to assume for cross-account access."}}},"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."}}}}},"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":"Reference to the integration app that defines this resource.\n\nThis field is only populated for resources that are part of an integration app.\nIt contains the unique identifier (_id) of the integration app (connector)\nthat defines the structure, behavior, and templates for this resource.\n\nThe integration app is the published template that can be installed\nmultiple times across different accounts, with each installation creating\na separate integration instance (referenced by _integrationId).\n\nThis reference enables:\n- Identifying the source integration app for this resource\n- Determining which template version is being used\n- Linking to documentation, support, and marketplace information\n"}}},"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"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\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":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```

## 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`) 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 `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"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":"Domain names used to validate OAuth URLs. Provide each\nunique domain once (no scheme, no path)."},"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":"Azure AD service principal credentials. Required when `provider`\nis `azureserviceprincipal`.","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."},"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 `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"certificate":{"type":"string","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. Returned masked."},"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."},"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":"Full Google service-account key file as a JSON string. Must parse\nas JSON and contain `project_id`, `client_email`, and a valid PEM\n`private_key` — otherwise the save fails with\nICLIENT_GOOGLESERVICEACCOUNT_INVALID_JSON_KEY (or _INVALID_PEM\nwhen only the key material is malformed). On update, omitting it\n(or sending the mask) keeps the stored credentials."},"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`.\nCeligo assumes `roleArn` using `externalId` as the trust-policy external ID.","required":["externalId"],"properties":{"externalId":{"type":"string","description":"External ID Celigo presents when assuming the role; must match the\n`sts:ExternalId` condition in the role's trust policy."},"roleArn":{"type":"string","description":"ARN of the AWS IAM role to assume for cross-account access."}}},"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."}}}}},"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":"Reference to the integration app that defines this resource.\n\nThis field is only populated for resources that are part of an integration app.\nIt contains the unique identifier (_id) of the integration app (connector)\nthat defines the structure, behavior, and templates for this resource.\n\nThe integration app is the published template that can be installed\nmultiple times across different accounts, with each installation creating\na separate integration instance (referenced by _integrationId).\n\nThis reference enables:\n- Identifying the source integration app for this resource\n- Determining which template version is being used\n- Linking to documentation, support, and marketplace information\n"}}},"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 iClient. 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.

```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`) 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`).\nFor `custom_oauth2`, credentials go in the `oauth2` sub-object.\nSecrets (`clientSecret`, `privateKey`, etc.) are returned masked\nas `\"******\"`. On update, re-send that masked value to keep the\nexisting secret; secrets are not preserved if omitted.","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 `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"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":"Domain names used to validate OAuth URLs. Provide each\nunique domain once (no scheme, no path)."},"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":"Azure AD service principal credentials. Required when `provider`\nis `azureserviceprincipal`.","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."},"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 `\"******\"`.\nRe-send that value on update to keep it; it is not preserved if omitted."},"certificate":{"type":"string","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. Returned masked."},"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."},"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":"Full Google service-account key file as a JSON string. Must parse\nas JSON and contain `project_id`, `client_email`, and a valid PEM\n`private_key` — otherwise the save fails with\nICLIENT_GOOGLESERVICEACCOUNT_INVALID_JSON_KEY (or _INVALID_PEM\nwhen only the key material is malformed). On update, omitting it\n(or sending the mask) keeps the stored credentials."},"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`.\nCeligo assumes `roleArn` using `externalId` as the trust-policy external ID.","required":["externalId"],"properties":{"externalId":{"type":"string","description":"External ID Celigo presents when assuming the role; must match the\n`sts:ExternalId` condition in the role's trust policy."},"roleArn":{"type":"string","description":"ARN of the AWS IAM role to assume for cross-account access."}}},"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."}}}}},"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":"Reference to the integration app that defines this resource.\n\nThis field is only populated for resources that are part of an integration app.\nIt contains the unique identifier (_id) of the integration app (connector)\nthat defines the structure, behavior, and templates for this resource.\n\nThe integration app is the published template that can be installed\nmultiple times across different accounts, with each installation creating\na separate integration instance (referenced by _integrationId).\n\nThis reference enables:\n- Identifying the source integration app for this resource\n- Determining which template version is being used\n- Linking to documentation, support, and marketplace information\n"}}},"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"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/iclients/{_id}":{"put":{"summary":"Update an iClient","description":"Replaces an iClient. All mutable fields must be provided — omitted\nfields are reset to defaults. Secrets returned as `\"******\"` can be\nsent back as-is to keep the existing value.","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":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```

## Delete an iClient

> Permanently deletes an iClient. Blocked if the iClient is still\
> referenced by a connection.

```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`) 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"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\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 if the iClient is still\nreferenced by a connection.","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":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```

## 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`) 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`) 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."},"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"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/api/api-reference/iclients.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.