Update Environment Integration

Update an existing environment integration. This can update fields like show_in_catalog, is_enabled, or override. You have the flexibility to customize an Integration and its configuration to better suit your specific needs. Customizing integrations allows you to override default settings, add new functionalities, and tailor the integration to fit seamlessly within your environment. Read more about Installing Integrations

Endpoint

http

PATCH /environment-integration/{id}

Path parameters

string · uuid

REQUIRED ·

The ID of the environment integration to update.

Example: 3fda2b4c-0516-41bc-8ae6-4927e42ecce9

Request Body

show_in_catalog

boolean

Whether to show this integration in the environment's catalog.

is_enabled

boolean

Whether the integration is enabled.

Example: true

override

object

An optional config override for the integration at environment level. Deep-merged on top of the base integration.config.

base_url

string

label

string

logo

string

icon

string

headers

object

query

object

query_array_format

string

All possible enum values:

comma
brackets
indices
repeat

actions

object

credentials

authorization

How Truto applies the resolved credential to outbound HTTP requests. The format discriminator selects which config shape applies.

All string values support Truto placeholders ({{path}}) resolved against the runtime context. Common placeholder roots: {{api_key}} for fields collected at connect time, {{oauth.token.access_token}} for OAuth2 access tokens, {{environment_variables.MY_KEY}} for env-vars set at the environment-integration level.

pagination

object

Pagination strategy for an integration or a single resource method. The format discriminator selects which config shape applies.

rate_limit

object

How Truto detects and reacts to upstream rate-limiting. All fields are JSONata expressions evaluated against the upstream response.

is_rate_limited

string

JSONata expression returning a truthy value when the response should be treated as rate-limited. When omitted, Truto falls back to status === 429.

Input: IntegrationRateLimitExpressionContext. Output: boolean.

Example: status = 429

retry_after_header_expression

string

JSONata expression returning the seconds to wait before retrying. When omitted, Truto reads the standard Retry-After header.

Input: IntegrationRateLimitExpressionContext. Output: number (seconds).

Example: $number(headers.`retry-after`)

rate_limit_header_expression

string

JSONata expression returning the current rate-limit window state. Truto forwards this as RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers in the proxy response.

Input: IntegrationRateLimitExpressionContext. Output: IntegrationRateLimitHeaderValues.

Example:

{ "limit": headers.`x-ratelimit-limit`, "remaining": headers.`x-ratelimit-remaining`, "reset": headers.`x-ratelimit-reset` }

resources

object

tool_tags

object

webhook

object

How Truto receives and verifies inbound webhooks for this integration. Not to be confused with WebhookSchema elsewhere in this spec, which describes Truto's outbound webhook delivered to your application.

signature_verification

Strategy used to verify the webhook signature before accepting it. Runs after payload_transform and after handle_verification returns { type: 'payload' }.

handle_verification

string

JSONata expression evaluated on every inbound webhook before signature verification. Use to:

Respond to handshake pings (return { type: 'verify', verification_response: { status_code, body, headers } }).
Surface meta-events that should not fan out (return { type: 'meta' }).
Update the integrated account context (return { type: 'verify' \| 'payload' \| 'meta', update_context: { ... } }).
Pass through to fan-out (return { type: 'payload' } or omit entirely — defaults to payload).

Input: IntegrationWebhookPayloadContext. Output: IntegrationWebhookHandleVerificationResult.

payload_transform

string

JSONata expression that transforms the raw inbound payload before handle_verification and signature_verification see it. Use to normalize vendor-specific envelopes (e.g. unwrap a Salesforce payloads[] array, decode a base64 body).

Input: IntegrationWebhookPayloadContext. Output: IntegrationWebhookPayloadContext (the same shape — what you return becomes the new payload).

error_expression

string

description

string

Environment-specific description shown in the catalog.

Response Body

string · uuid

The ID of the environment integration.

Example: 3fda2b4c-0516-41bc-8ae6-4927e42ecce9

integration_id

string · uuid

The ID of the integration this environment integration references.

Example: 4a4de828-f4db-4c9e-adfd-434e0864c3c7

environment_id

string · uuid

The ID of the environment in which this integration is installed.

Example: 8a2b104d-74a6-47f2-b93e-c6b611e82391

show_in_catalog

boolean

Whether this integration is shown in the environment's catalog.

Example: true

is_enabled

boolean

Whether this integration is enabled in the environment.

Example: true

created_at

string · date-time

The date and time when the environment integration was created.

Example: 2021-08-10T10:00:00.000Z

updated_at

string · date-time

The date and time when the environment integration was last updated.

Example: 2021-08-10T10:00:00.000Z

integration

object

The referenced integration object.

string · uuid

The ID of the integration.

Example: 4a4de828-f4db-4c9e-adfd-434e0864c3c7

name

string

The name of the integration.

Example: zendesk

category

string

The category of the integration.

Example: helpdesk

is_beta

boolean

Whether the integration is in beta or not. Beta integrations might not have been tested completely and are not recommended for production environments.

config

object

The configuration object defining the underlying API of the integration.

Example:

{
  "base_url": "https://api.example.com",
  "label": "Example API Integration",
  "logo": "https://example.com/logo.png",
  "icon": "https://example.com/icon.png",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "User-Agent": "truto"
  },
  "query": {
    "search": "{{search_query}}",
    "filter": "{{filter_criteria}}"
  },
  "query_array_format": "comma",
  "actions": {
    "sync_users": {
      "type": "request",
      "config": {
        "method": "post",
        "path": "/sync/users",
        "headers": {
          "Authorization": "Bearer {{oauth.token.access_token}}"
        },
        "body": {
          "users": "{{context.users}}"
        }
      }
    }
  },
  "credentials": {
    "oauth2": {
      "format": "oauth2",
      "config": {
        "client": {
          "id": "your-client-id",
          "secret": "your-client-secret"
        },
        "auth": {
          "tokenHost": "https://auth.example.com",
          "tokenPath": "/oauth/token",
          "refreshPath": "/oauth/refresh"
        },
        "options": {
          "scopeSeparator": " ",
          "authorizationMethod": "header",
          "bodyFormat": "form"
        },
        "fields": [
          {
            "name": "client_id",
            "label": "Client ID",
            "type": "text",
            "required": true
          },
          {
            "name": "client_secret",
            "label": "Client Secret",
            "type": "password",
            "required": true
          }
        ],
        "tokenParams": {
          "grant_type": "client_credentials"
        },
        "refreshParams": {
          "grant_type": "refresh_token"
        },
        "tokenExpiryDuration": "3600"
      }
    }
  },
  "authorization": {
    "format": "bearer",
    "config": {
      "token": "{{oauth.token.access_token}}"
    }
  },
  "pagination": {
    "format": "page",
    "config": {
      "page_key": "page",
      "limit_key": "per_page"
    }
  },
  "rate_limit": {
    "is_rate_limited": true,
    "retry_after_header_expression": "Retry-After",
    "rate_limit_header_expression": "X-RateLimit-Remaining"
  },
  "resources": {
    "users": {
      "list": {
        "method": "get",
        "path": "/users",
        "response_path": "data.users",
        "headers": {
          "Authorization": "Bearer {{oauth.token.access_token}}"
        },
        "query": {
          "page": "{{pagination.page}}",
          "per_page": "{{pagination.per_page}}"
        },
        "pagination": {
          "format": "page",
          "config": {
            "page_key": "page",
            "limit_key": "per_page"
          }
        },
        "authorization": {
          "format": "bearer",
          "config": {
            "token": "{{oauth.token.access_token}}"
          }
        },
        "rate_limit": {
          "is_rate_limited": true,
          "retry_after_header_expression": "Retry-After",
          "rate_limit_header_expression": "X-RateLimit-Remaining"
        },
        "examples": {
          "response": "{\n  \"data\": {\n    \"users\": [\n      {\n        \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n        \"name\": \"John Doe\",\n        \"email\": \"john.doe@example.com\"\n      }\n    ]\n  }\n}\n"
        }
      }
    },
    "orders": {
      "create": {
        "method": "post",
        "path": "/orders",
        "body": {
          "user_id": "{{context.user_id}}",
          "items": "{{context.items}}"
        },
        "response_path": "data.order",
        "headers": {
          "Authorization": "Bearer {{oauth.token.access_token}}"
        },
        "authorization": {
          "format": "bearer",
          "config": {
            "value": "{{oauth.token.access_token}}"
          }
        }
      }
    }
  },
  "webhook": {
    "signature_verification": {
      "format": "hmac",
      "config": {
        "secret": "{{environment_variables.WEBHOOK_SECRET}}",
        "algorithm": "sha256",
        "string_type": "hex",
        "compare_with": "{{headers.x-signature}}",
        "parts": [
          "raw_body"
        ]
      }
    },
    "handle_verification": "{ 'type': webhook_type = 'verify' ? 'verify' : 'payload', 'verification_response': webhook_type = 'verify' ? { 'body': { 'challenge': body.challenge } } }"
  },
  "error_expression": "status >= 400 ? { 'status': status, 'message': data.error.message }"
}

base_url

string

Default base URL prepended to every resource method's path.

Example: https://api.example.com

label

string

Human-readable name shown in the Truto Dashboard and Link UI.

Example: Example API

logo

string

URL to the integration logo (square, recommended 256x256).

icon

string

URL to a smaller monochrome icon used in catalog listings.

headers

object

Default HTTP headers merged into every outbound request. Values may be templated with JSONata placeholders.

query

object

Default query-string params merged into every outbound request.

query_array_format

string

All possible enum values:

comma
brackets
indices
repeat

actions

object

Named integration actions. Reserved keys (post_install, post_connect_user_form, refresh_token, validation) hook into specific platform lifecycle events; custom names are callable from the proxy/sync runtime.

credentials

Either a single credential definition (when the integration only supports one auth format) or a map keyed by auth format (when an integration supports multiple, e.g. api_key and oauth2). For multi-format integrations, the customer picks one in the Link UI.

authorization

How Truto applies the resolved credential to outbound HTTP requests. The format discriminator selects which config shape applies.

pagination

object

Pagination strategy for an integration or a single resource method. The format discriminator selects which config shape applies.

rate_limit

object

How Truto detects and reacts to upstream rate-limiting. All fields are JSONata expressions evaluated against the upstream response.

is_rate_limited

string

JSONata expression returning a truthy value when the response should be treated as rate-limited. When omitted, Truto falls back to status === 429.

Input: IntegrationRateLimitExpressionContext. Output: boolean.

Example: status = 429

retry_after_header_expression

string

JSONata expression returning the seconds to wait before retrying. When omitted, Truto reads the standard Retry-After header.

Input: IntegrationRateLimitExpressionContext. Output: number (seconds).

Example: $number(headers.`retry-after`)

rate_limit_header_expression

string

JSONata expression returning the current rate-limit window state. Truto forwards this as RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers in the proxy response.

Input: IntegrationRateLimitExpressionContext. Output: IntegrationRateLimitHeaderValues.

Example:

{ "limit": headers.`x-ratelimit-limit`, "remaining": headers.`x-ratelimit-remaining`, "reset": headers.`x-ratelimit-reset` }

resources

object

Resource → method tree (e.g. resources.users.list). The inner key is one of the canonical methods (list, get, create, update, delete) or a custom method name. Each method definition matches IntegrationResourceMethod.

tool_tags

object

Optional tag arrays per resource, surfaced via the Truto MCP tools listing.

webhook

object

signature_verification

Strategy used to verify the webhook signature before accepting it. Runs after payload_transform and after handle_verification returns { type: 'payload' }.

handle_verification

string

JSONata expression evaluated on every inbound webhook before signature verification. Use to:

Respond to handshake pings (return { type: 'verify', verification_response: { status_code, body, headers } }).
Surface meta-events that should not fan out (return { type: 'meta' }).
Update the integrated account context (return { type: 'verify' \| 'payload' \| 'meta', update_context: { ... } }).
Pass through to fan-out (return { type: 'payload' } or omit entirely — defaults to payload).

Input: IntegrationWebhookPayloadContext. Output: IntegrationWebhookHandleVerificationResult.

payload_transform

string

Input: IntegrationWebhookPayloadContext. Output: IntegrationWebhookPayloadContext (the same shape — what you return becomes the new payload).

error_expression

string

Integration-wide JSONata expression evaluated on every response. Use to detect errors in successful (2xx) responses, normalize error messages, or transform "errors" with < 400 status into successful responses. Overridden by per-method IntegrationResourceMethod.error_expression when set.

Input: IntegrationErrorExpressionContext. Output: IntegrationErrorExpressionResult — return null/undefined to indicate "no error", or a { status, message?, headers?, metadata?, result? } object.

team_id

string · uuid

The ID of the team that owns this integration.

Example: 05daecaf-4365-42e8-8370-8127de5dd717

sharing

string

The sharing policy of the integration.

All possible enum values:

allow
ask
deny

Example: allow

created_at

string · date-time

The date and time when the integration was created.

Example: 2021-08-10T10:00:00.000Z

updated_at

string · date-time

The date and time when the integration was last updated.

Example: 2021-08-10T10:00:00.000Z

installed_environment

string[]

A list of environment IDs where this integration is installed.

team

object

The team that owns this integration.

string · uuid

The ID of the team.

Example: 05daecaf-4365-42e8-8370-8127de5dd717

name

string

The name of the team.

Example: My Awesome Team

domain

string

The domain of the team.

Example: example.com

logo

string

The URL of the team's logo.

Example: https://example.com/logo.png

is_verified

boolean

Whether the team is verified or not.

Example: true

is_white_label

boolean

Whether the team is white-labeled or not.

tos_link

string

A link to the team's Terms of Service, if available.

Example: https://example.com/tos

allow_impersonation

boolean

Whether the team allows impersonation.

created_at

string · date-time

The date and time when the team was created.

Example: 2021-08-10T10:00:00.000Z

updated_at

string · date-time

The date and time when the team was last updated.

Example: 2021-08-10T10:00:00.000Z

override

object

An optional config override applied for the integration at environment level. Deep-merged on top of the base integration.config at request time.

base_url

string

label

string

logo

string

icon

string

headers

object

query

object

query_array_format

string

All possible enum values:

comma
brackets
indices
repeat

actions

object

credentials

authorization

How Truto applies the resolved credential to outbound HTTP requests. The format discriminator selects which config shape applies.

pagination

object

Pagination strategy for an integration or a single resource method. The format discriminator selects which config shape applies.

rate_limit

object

How Truto detects and reacts to upstream rate-limiting. All fields are JSONata expressions evaluated against the upstream response.

is_rate_limited

string

JSONata expression returning a truthy value when the response should be treated as rate-limited. When omitted, Truto falls back to status === 429.

Input: IntegrationRateLimitExpressionContext. Output: boolean.

Example: status = 429

retry_after_header_expression

string

JSONata expression returning the seconds to wait before retrying. When omitted, Truto reads the standard Retry-After header.

Input: IntegrationRateLimitExpressionContext. Output: number (seconds).

Example: $number(headers.`retry-after`)

rate_limit_header_expression

string

JSONata expression returning the current rate-limit window state. Truto forwards this as RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers in the proxy response.

Input: IntegrationRateLimitExpressionContext. Output: IntegrationRateLimitHeaderValues.

Example:

{ "limit": headers.`x-ratelimit-limit`, "remaining": headers.`x-ratelimit-remaining`, "reset": headers.`x-ratelimit-reset` }

resources

object

tool_tags

object

webhook

object

signature_verification

Strategy used to verify the webhook signature before accepting it. Runs after payload_transform and after handle_verification returns { type: 'payload' }.

handle_verification

string

JSONata expression evaluated on every inbound webhook before signature verification. Use to:

Respond to handshake pings (return { type: 'verify', verification_response: { status_code, body, headers } }).
Surface meta-events that should not fan out (return { type: 'meta' }).
Update the integrated account context (return { type: 'verify' \| 'payload' \| 'meta', update_context: { ... } }).
Pass through to fan-out (return { type: 'payload' } or omit entirely — defaults to payload).

Input: IntegrationWebhookPayloadContext. Output: IntegrationWebhookHandleVerificationResult.

payload_transform

string

Input: IntegrationWebhookPayloadContext. Output: IntegrationWebhookPayloadContext (the same shape — what you return becomes the new payload).

error_expression

string

description

string

Environment-specific description shown in the catalog.