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
Returns all iClients in the account. Does not paginate — all iClients are returned in a single response.
Maximum number of records to return per page.
100Opaque cursor for forward pagination. Pass the value from the Link
response header (rel="next") to fetch the next page.
List of iClients (may be empty).
No iClients exist in the account.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
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"
}
}
]Creates a new iClient. The provider field is required and determines which credential sub-object must be populated.
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.
Display name for the iClient.
Google Drive OAuth AppAuthentication provider that determines which credential fields apply.
When true, this iClient is published and available for use.
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.
When true, other resources can reference this iClient's fields via Handlebars expressions.
UI form type. Set automatically by the UI: assistant when
_httpConnectorId is present, http otherwise.
HTTP connector backing this iClient's guided setup.
5d2e9c8b7a6f4e3d2c1b0a99HTTP connector API definition linked to this iClient.
669e1d90e3e73a17fb1fb1ebConnector-specific settings (e.g. region, environment, instance URI). Shape varies by connector.
Dynamic UI form definition for the settings object.
iClient created.
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).
Display name for the iClient.
Google Drive OAuth AppAuthentication provider that determines which credential fields apply.
When true, this iClient is published and available for use.
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.
When true, other resources can reference this iClient's fields via Handlebars expressions.
UI form type. Set automatically by the UI: assistant when
_httpConnectorId is present, http otherwise.
HTTP connector backing this iClient's guided setup.
5d2e9c8b7a6f4e3d2c1b0a99HTTP connector API definition linked to this iClient.
669e1d90e3e73a17fb1fb1ebConnector-specific settings (e.g. region, environment, instance URI). Shape varies by connector.
Dynamic UI form definition for the settings object.
Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZReference 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)
5f9a7b2c3d4e5f6a7b8c9d0eReference 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
5e8d43a1b9e5a80011a35f1bBad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Forbidden. The authenticated caller does not have permission to perform this operation.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
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
}
}Retrieves a single iClient by ID.
iClient ID.
iClient object.
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).
Display name for the iClient.
Google Drive OAuth AppAuthentication provider that determines which credential fields apply.
When true, this iClient is published and available for use.
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.
When true, other resources can reference this iClient's fields via Handlebars expressions.
UI form type. Set automatically by the UI: assistant when
_httpConnectorId is present, http otherwise.
HTTP connector backing this iClient's guided setup.
5d2e9c8b7a6f4e3d2c1b0a99HTTP connector API definition linked to this iClient.
669e1d90e3e73a17fb1fb1ebConnector-specific settings (e.g. region, environment, instance URI). Shape varies by connector.
Dynamic UI form definition for the settings object.
Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZReference 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)
5f9a7b2c3d4e5f6a7b8c9d0eReference 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
5e8d43a1b9e5a80011a35f1bUnauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
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"
}
}
}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.
iClient ID.
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.
Display name for the iClient.
Google Drive OAuth AppAuthentication provider that determines which credential fields apply.
When true, this iClient is published and available for use.
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.
When true, other resources can reference this iClient's fields via Handlebars expressions.
UI form type. Set automatically by the UI: assistant when
_httpConnectorId is present, http otherwise.
HTTP connector backing this iClient's guided setup.
5d2e9c8b7a6f4e3d2c1b0a99HTTP connector API definition linked to this iClient.
669e1d90e3e73a17fb1fb1ebConnector-specific settings (e.g. region, environment, instance URI). Shape varies by connector.
Dynamic UI form definition for the settings object.
Updated iClient.
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).
Display name for the iClient.
Google Drive OAuth AppAuthentication provider that determines which credential fields apply.
When true, this iClient is published and available for use.
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.
When true, other resources can reference this iClient's fields via Handlebars expressions.
UI form type. Set automatically by the UI: assistant when
_httpConnectorId is present, http otherwise.
HTTP connector backing this iClient's guided setup.
5d2e9c8b7a6f4e3d2c1b0a99HTTP connector API definition linked to this iClient.
669e1d90e3e73a17fb1fb1ebConnector-specific settings (e.g. region, environment, instance URI). Shape varies by connector.
Dynamic UI form definition for the settings object.
Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZReference 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)
5f9a7b2c3d4e5f6a7b8c9d0eReference 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
5e8d43a1b9e5a80011a35f1bBad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
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
}
}Permanently deletes an iClient. Blocked if the iClient is still referenced by a connection.
iClient ID.
iClient deleted (no response body).
No content
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
DELETE /v1/iclients/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Partially updates an iClient using JSON Patch (RFC 6902). Only /oauth2/failPath is patchable; use PUT for other field changes.
iClient ID.
JSON Patch operation.
JSON Pointer to modify. Only /oauth2/failPath is
whitelisted.
New value. Required for replace and add;
omit for remove.
Patch applied (no response body).
No content
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Patch rejected.
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
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.
Resource ID.
Dependency map. Keys are resource-type strings; values are arrays
of dependency entries. Returns {} when no dependents exist.
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.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
GET /v1/iclients/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}Last updated
Was this helpful?