For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

List iClients

get
/v1/iclients

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

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
limitinteger · min: 1Optional

Maximum number of records to return per page.

Example: 100
afterstringOptional

Opaque cursor for forward pagination. Pass the value from the Link response header (rel="next") to fetch the next page.

Responses
200

List of iClients (may be empty).

application/json
get/v1/iclients
GET /v1/iclients HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
  {
    "_id": "664be9dc9f7cf79527e2c03e",
    "name": "Google Drive",
    "published": false,
    "lastModified": "2024-05-21T00:25:00.735Z",
    "provider": "custom_oauth2",
    "_httpConnectorId": "669e1d90e3e73a17fb1fb1eb",
    "_httpConnectorApiId": "66a0a457ea5ed5b80f6efa74",
    "enableJWT": false,
    "enableIClientReferences": false,
    "formType": "assistant",
    "oauth2": {
      "clientId": "1096775564568-cucr5sv44tgfec4kkqsufi5k975d8orv.apps.googleusercontent.com",
      "clientSecret": "******",
      "scope": [],
      "scopeDelimiter": " ",
      "validDomainNames": [
        "google.com"
      ],
      "useNewAuthFailSchema": true,
      "auth": {
        "uri": "https://accounts.google.com/o/oauth2/auth"
      },
      "token": {
        "uri": "https://accounts.google.com/o/oauth2/token"
      }
    }
  },
  {
    "_id": "69e83183438f9e0edcc68c49",
    "name": "Azure Service Principal",
    "published": false,
    "lastModified": "2026-05-02T18:09:32.572Z",
    "provider": "azureserviceprincipal",
    "enableJWT": false,
    "enableIClientReferences": false,
    "formType": "http",
    "azureserviceprincipal": {
      "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "clientSecret": "******",
      "tenantId": "f0e1d2c3-b4a5-6789-0abc-def012345678"
    }
  }
]

Create an iClient

post
/v1/iclients

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

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

iClient configuration. The shape varies by provider — each provider requires its own credential sub-object (oauth2, netsuite, salesforce, ebay, amazonmws, azureserviceprincipal). For custom_oauth2, credentials go in the oauth2 sub-object. Secrets (clientSecret, privateKey, etc.) are returned masked as "******". On update, re-send that masked value to keep the existing secret; secrets are not preserved if omitted.

namestringOptional

Display name for the iClient.

Example: Google Drive OAuth App
providerstring · enumRequired

Authentication provider that determines which credential fields apply.

Possible values:
publishedbooleanOptional

When true, this iClient is published and available for use.

enableJWTbooleanOptional

Enables a JWT assertion as part of the OAuth token request. When true, {{{iClient.jwt.token}}} resolves to the signed JWT for use in the token URL request body. Requires the jwt sub-object to be configured.

enableIClientReferencesbooleanOptional

When true, other resources can reference this iClient's fields via Handlebars expressions.

formTypestring · enumOptional

UI form type. Set automatically by the UI: assistant when _httpConnectorId is present, http otherwise.

Possible values:
_httpConnectorIdstring · objectIdOptional

HTTP connector backing this iClient's guided setup.

Example: 5d2e9c8b7a6f4e3d2c1b0a99
_httpConnectorApiIdstring · objectIdOptional

HTTP connector API definition linked to this iClient.

Example: 669e1d90e3e73a17fb1fb1eb
settingsobjectOptional

Connector-specific settings (e.g. region, environment, instance URI). Shape varies by connector.

settingsFormobjectOptional

Dynamic UI form definition for the settings object.

Responses
201

iClient created.

application/json

iClient object as returned by the API. Includes all request fields plus server-managed metadata. name is optional on create and is omitted from GET responses when the iClient was created without one (the create response echoes it as null).

namestringOptional

Display name for the iClient.

Example: Google Drive OAuth App
providerstring · enumRequired

Authentication provider that determines which credential fields apply.

Possible values:
publishedbooleanOptional

When true, this iClient is published and available for use.

enableJWTbooleanOptional

Enables a JWT assertion as part of the OAuth token request. When true, {{{iClient.jwt.token}}} resolves to the signed JWT for use in the token URL request body. Requires the jwt sub-object to be configured.

enableIClientReferencesbooleanOptional

When true, other resources can reference this iClient's fields via Handlebars expressions.

formTypestring · enumOptional

UI form type. Set automatically by the UI: assistant when _httpConnectorId is present, http otherwise.

Possible values:
_httpConnectorIdstring · objectIdOptional

HTTP connector backing this iClient's guided setup.

Example: 5d2e9c8b7a6f4e3d2c1b0a99
_httpConnectorApiIdstring · objectIdOptional

HTTP connector API definition linked to this iClient.

Example: 669e1d90e3e73a17fb1fb1eb
settingsobjectOptional

Connector-specific settings (e.g. region, environment, instance URI). Shape varies by connector.

settingsFormobjectOptional

Dynamic UI form definition for the settings object.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c
createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z
lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z
deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z
_integrationIdstring · objectIdRead-onlyOptional

Reference to the specific integration instance that contains this resource.

This field is only populated for resources that are part of an integration app installation. It contains the unique identifier (_id) of the integration resource that was installed in the account.

The integration instance represents a specific installed instance of an integration app, with its own configuration, settings, and runtime environment.

This reference enables:

  • Tracing the resource back to its parent integration instance
  • Permission and access control based on integration ownership
  • Lifecycle management (enabling/disabling, updating, or uninstalling)
Example: 5f9a7b2c3d4e5f6a7b8c9d0e
_connectorIdstring · objectIdRead-onlyOptional

Reference to the integration app that defines this resource.

This field is only populated for resources that are part of an integration app. It contains the unique identifier (_id) of the integration app (connector) that defines the structure, behavior, and templates for this resource.

The integration app is the published template that can be installed multiple times across different accounts, with each installation creating a separate integration instance (referenced by _integrationId).

This reference enables:

  • Identifying the source integration app for this resource
  • Determining which template version is being used
  • Linking to documentation, support, and marketplace information
Example: 5e8d43a1b9e5a80011a35f1b
post/v1/iclients
POST /v1/iclients HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 245

{
  "name": "My OAuth App",
  "provider": "custom_oauth2",
  "oauth2": {
    "clientId": "my-client-id",
    "clientSecret": "my-client-secret",
    "scope": [
      "read write"
    ],
    "auth": {
      "uri": "https://auth.example.com/authorize"
    },
    "token": {
      "uri": "https://auth.example.com/token"
    }
  }
}
{
  "_id": "69e83183438f9e0edcc68c49",
  "name": "Client Credentials App",
  "published": false,
  "lastModified": "2026-05-02T18:09:32.572Z",
  "provider": "custom_oauth2",
  "enableJWT": false,
  "enableIClientReferences": false,
  "formType": "http",
  "oauth2": {
    "clientId": "cid",
    "clientSecret": "******",
    "scope": [],
    "validDomainNames": [
      "example.com"
    ],
    "grantType": "clientcredentials",
    "useNewAuthFailSchema": true
  }
}

Get an iClient

get
/v1/iclients/{_id}

Retrieves a single iClient by ID.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

iClient ID.

Responses
200

iClient object.

application/json

iClient object as returned by the API. Includes all request fields plus server-managed metadata. name is optional on create and is omitted from GET responses when the iClient was created without one (the create response echoes it as null).

namestringOptional

Display name for the iClient.

Example: Google Drive OAuth App
providerstring · enumRequired

Authentication provider that determines which credential fields apply.

Possible values:
publishedbooleanOptional

When true, this iClient is published and available for use.

enableJWTbooleanOptional

Enables a JWT assertion as part of the OAuth token request. When true, {{{iClient.jwt.token}}} resolves to the signed JWT for use in the token URL request body. Requires the jwt sub-object to be configured.

enableIClientReferencesbooleanOptional

When true, other resources can reference this iClient's fields via Handlebars expressions.

formTypestring · enumOptional

UI form type. Set automatically by the UI: assistant when _httpConnectorId is present, http otherwise.

Possible values:
_httpConnectorIdstring · objectIdOptional

HTTP connector backing this iClient's guided setup.

Example: 5d2e9c8b7a6f4e3d2c1b0a99
_httpConnectorApiIdstring · objectIdOptional

HTTP connector API definition linked to this iClient.

Example: 669e1d90e3e73a17fb1fb1eb
settingsobjectOptional

Connector-specific settings (e.g. region, environment, instance URI). Shape varies by connector.

settingsFormobjectOptional

Dynamic UI form definition for the settings object.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c
createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z
lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z
deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z
_integrationIdstring · objectIdRead-onlyOptional

Reference to the specific integration instance that contains this resource.

This field is only populated for resources that are part of an integration app installation. It contains the unique identifier (_id) of the integration resource that was installed in the account.

The integration instance represents a specific installed instance of an integration app, with its own configuration, settings, and runtime environment.

This reference enables:

  • Tracing the resource back to its parent integration instance
  • Permission and access control based on integration ownership
  • Lifecycle management (enabling/disabling, updating, or uninstalling)
Example: 5f9a7b2c3d4e5f6a7b8c9d0e
_connectorIdstring · objectIdRead-onlyOptional

Reference to the integration app that defines this resource.

This field is only populated for resources that are part of an integration app. It contains the unique identifier (_id) of the integration app (connector) that defines the structure, behavior, and templates for this resource.

The integration app is the published template that can be installed multiple times across different accounts, with each installation creating a separate integration instance (referenced by _integrationId).

This reference enables:

  • Identifying the source integration app for this resource
  • Determining which template version is being used
  • Linking to documentation, support, and marketplace information
Example: 5e8d43a1b9e5a80011a35f1b
get/v1/iclients/{_id}
GET /v1/iclients/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "_id": "664be9dc9f7cf79527e2c03e",
  "name": "Google Drive",
  "published": false,
  "lastModified": "2024-05-21T00:25:00.735Z",
  "provider": "custom_oauth2",
  "_httpConnectorId": "669e1d90e3e73a17fb1fb1eb",
  "_httpConnectorApiId": "66a0a457ea5ed5b80f6efa74",
  "enableJWT": false,
  "enableIClientReferences": false,
  "formType": "assistant",
  "oauth2": {
    "clientId": "1096775564568-cucr5sv44tgfec4kkqsufi5k975d8orv.apps.googleusercontent.com",
    "clientSecret": "******",
    "scope": [],
    "scopeDelimiter": " ",
    "validDomainNames": [
      "google.com"
    ],
    "useNewAuthFailSchema": true,
    "auth": {
      "uri": "https://accounts.google.com/o/oauth2/auth"
    },
    "token": {
      "uri": "https://accounts.google.com/o/oauth2/token"
    }
  }
}

Update an iClient

put
/v1/iclients/{_id}

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.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

iClient ID.

Body

iClient configuration. The shape varies by provider — each provider requires its own credential sub-object (oauth2, netsuite, salesforce, ebay, amazonmws, azureserviceprincipal). For custom_oauth2, credentials go in the oauth2 sub-object. Secrets (clientSecret, privateKey, etc.) are returned masked as "******". On update, re-send that masked value to keep the existing secret; secrets are not preserved if omitted.

namestringOptional

Display name for the iClient.

Example: Google Drive OAuth App
providerstring · enumRequired

Authentication provider that determines which credential fields apply.

Possible values:
publishedbooleanOptional

When true, this iClient is published and available for use.

enableJWTbooleanOptional

Enables a JWT assertion as part of the OAuth token request. When true, {{{iClient.jwt.token}}} resolves to the signed JWT for use in the token URL request body. Requires the jwt sub-object to be configured.

enableIClientReferencesbooleanOptional

When true, other resources can reference this iClient's fields via Handlebars expressions.

formTypestring · enumOptional

UI form type. Set automatically by the UI: assistant when _httpConnectorId is present, http otherwise.

Possible values:
_httpConnectorIdstring · objectIdOptional

HTTP connector backing this iClient's guided setup.

Example: 5d2e9c8b7a6f4e3d2c1b0a99
_httpConnectorApiIdstring · objectIdOptional

HTTP connector API definition linked to this iClient.

Example: 669e1d90e3e73a17fb1fb1eb
settingsobjectOptional

Connector-specific settings (e.g. region, environment, instance URI). Shape varies by connector.

settingsFormobjectOptional

Dynamic UI form definition for the settings object.

Responses
200

Updated iClient.

application/json

iClient object as returned by the API. Includes all request fields plus server-managed metadata. name is optional on create and is omitted from GET responses when the iClient was created without one (the create response echoes it as null).

namestringOptional

Display name for the iClient.

Example: Google Drive OAuth App
providerstring · enumRequired

Authentication provider that determines which credential fields apply.

Possible values:
publishedbooleanOptional

When true, this iClient is published and available for use.

enableJWTbooleanOptional

Enables a JWT assertion as part of the OAuth token request. When true, {{{iClient.jwt.token}}} resolves to the signed JWT for use in the token URL request body. Requires the jwt sub-object to be configured.

enableIClientReferencesbooleanOptional

When true, other resources can reference this iClient's fields via Handlebars expressions.

formTypestring · enumOptional

UI form type. Set automatically by the UI: assistant when _httpConnectorId is present, http otherwise.

Possible values:
_httpConnectorIdstring · objectIdOptional

HTTP connector backing this iClient's guided setup.

Example: 5d2e9c8b7a6f4e3d2c1b0a99
_httpConnectorApiIdstring · objectIdOptional

HTTP connector API definition linked to this iClient.

Example: 669e1d90e3e73a17fb1fb1eb
settingsobjectOptional

Connector-specific settings (e.g. region, environment, instance URI). Shape varies by connector.

settingsFormobjectOptional

Dynamic UI form definition for the settings object.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c
createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z
lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z
deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z
_integrationIdstring · objectIdRead-onlyOptional

Reference to the specific integration instance that contains this resource.

This field is only populated for resources that are part of an integration app installation. It contains the unique identifier (_id) of the integration resource that was installed in the account.

The integration instance represents a specific installed instance of an integration app, with its own configuration, settings, and runtime environment.

This reference enables:

  • Tracing the resource back to its parent integration instance
  • Permission and access control based on integration ownership
  • Lifecycle management (enabling/disabling, updating, or uninstalling)
Example: 5f9a7b2c3d4e5f6a7b8c9d0e
_connectorIdstring · objectIdRead-onlyOptional

Reference to the integration app that defines this resource.

This field is only populated for resources that are part of an integration app. It contains the unique identifier (_id) of the integration app (connector) that defines the structure, behavior, and templates for this resource.

The integration app is the published template that can be installed multiple times across different accounts, with each installation creating a separate integration instance (referenced by _integrationId).

This reference enables:

  • Identifying the source integration app for this resource
  • Determining which template version is being used
  • Linking to documentation, support, and marketplace information
Example: 5e8d43a1b9e5a80011a35f1b
put/v1/iclients/{_id}
PUT /v1/iclients/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 116

{
  "name": "Renamed OAuth App",
  "provider": "custom_oauth2",
  "oauth2": {
    "clientId": "my-client-id",
    "clientSecret": "******"
  }
}
{
  "_id": "69e83183438f9e0edcc68c49",
  "name": "Renamed OAuth App",
  "published": false,
  "lastModified": "2026-05-02T18:14:05.118Z",
  "provider": "custom_oauth2",
  "enableJWT": false,
  "enableIClientReferences": false,
  "formType": "http",
  "oauth2": {
    "clientId": "my-client-id",
    "clientSecret": "******",
    "scope": [],
    "useNewAuthFailSchema": true
  }
}

Delete an iClient

delete
/v1/iclients/{_id}

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

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

iClient ID.

Responses
204

iClient deleted (no response body).

No content

delete/v1/iclients/{_id}
DELETE /v1/iclients/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Patch an iClient

patch
/v1/iclients/{_id}

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

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

iClient ID.

Bodyobject[]
opstring · enumRequired

JSON Patch operation.

Possible values:
pathstring · enumRequired

JSON Pointer to modify. Only /oauth2/failPath is whitelisted.

Possible values:
valuestringOptional

New value. Required for replace and add; omit for remove.

Responses
204

Patch applied (no response body).

No content

patch/v1/iclients/{_id}
PATCH /v1/iclients/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 68

[
  {
    "op": "replace",
    "path": "/oauth2/failPath",
    "value": "error.message"
  }
]

No content

List dependencies of an iClient

get
/v1/iclients/{_id}/dependencies

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.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

Resource ID.

Responses
200

Dependency map. Keys are resource-type strings; values are arrays of dependency entries. Returns {} when no dependents exist.

application/json

Map of dependent-resource types to arrays of dependency entries. Keys are plural resource type strings (e.g. flows, imports, connections). An empty object {} means no dependents.

get/v1/iclients/{_id}/dependencies
GET /v1/iclients/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}

Last updated

Was this helpful?