Skip to content

Installed Integrations - Environment Integrations Object

Properties

created_atstring · date-time

The date and time when the environment integration was created.

Example: 2021-08-10T10:00:00.000Z
environment_idstring · uuid

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

Example: 8a2b104d-74a6-47f2-b93e-c6b611e82391
idstring · uuid

The ID of the environment integration.

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

The category of the integration.

Example: helpdesk
configobject

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 }"
}
16 properties
actionsRecord<string, any>

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.

authorizationobject

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.

One of
bearer · 2 properties
configobject
required
1 property
valuestring

The bearer token. Almost always a placeholder like {{oauth.token.access_token}} (OAuth2) or {{api_key}} (api-key fields).

Example: {{oauth.token.access_token}}
formatstring
Possible values:
bearer
basic · 2 properties
configobject
2 properties
passwordstring

Password, supports placeholders.

Example: {{client_secret}}
usernamestring

Username, supports placeholders (e.g. {{api_key}} for vendors that pass the API key as the username).

Example: {{client_id}}
formatstring
Possible values:
basic
header · 2 properties
configobject
2 properties
expressionstring

JSONata expression that fully constructs the outgoing request. Use for advanced cases (request signing, dynamic URL rewrites).

Input: IntegrationHeaderAuthorizationContext. Output: IntegrationHeaderAuthorizationResult (must contain url and requestOptions).

headersRecord<string, any>

Map of header name → value. Values support placeholders (e.g. { "X-API-Key": "{{api_key}}" }).

Example: {"X-API-Key":"{{api_key}}","X-Account-Id":"{{account_id}}"}
formatstring
Possible values:
header
base_urlstring

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

Example: https://api.example.com
credentialsobject | Record<string, any>

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.

error_expressionstring

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.

headersRecord<string, any>

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

iconstring

URL to a smaller monochrome icon used in catalog listings.

labelstring

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

Example: Example API
logostring

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

paginationobject

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

One of
page · 2 properties
configobject

Page-number pagination options. All fields optional; defaults shown.

9 properties
add_to_bodyboolean

Add pagination keys to the request body instead of the query string.

add_to_queryboolean

Add pagination keys to the query string. Defaults to true when add_to_body is false.

headersRecord<string, any>

Static or templated headers added to every paginated request. Templated against the request query plus a synthetic limit.

ignore_limitboolean

Drop the limit_key from the URL after pagination is applied (for APIs that 400 on it).

limit_keystring

Query/body key that holds the page size.

max_limitinteger

Maximum page size Truto will request, regardless of the caller's limit.

page_keystring

Query/body key that holds the page number.

starting_pagestring

Page number used for the first page (some APIs are 0-indexed).

use_content_hashboolean

Stop paginating when consecutive pages return identical results (loop detection). Defaults to true.

formatstring
Possible values:
page
cursor · 2 properties
configobject
required·

Cursor pagination options.

17 properties
add_to_bodyboolean

Send the cursor in the request body instead of the URL.

add_to_queryboolean

Add the cursor to the query string.

allow_empty_page_cursorboolean

Don't treat an empty cursor as the end of pagination.

cursor_keystring

Query/body key Truto uses to send the cursor on the next request.

cursor_pathstring

Dotted-path accessor into the response body (or headers, when cursor_path_object: header) that yields the next cursor.

Example: data.meta.next_cursor
cursor_path_objectstring

Where to read cursor_path from.

Possible values:
bodyheader
has_next_pathstring

Optional accessor that returns a truthy/"true"/"false" value indicating whether more pages exist.

headersRecord<string, any>

Static or templated headers added to every paginated request. Templated against the request query plus a synthetic limit.

ignore_limit_in_paginationboolean

Don't re-send limit_key after the first page (for APIs that reject it on subsequent calls).

include_pathboolean

When is_link is true, also overwrite the request path with the link's path (not just the query string).

is_cursor_url_encodedboolean

URL-decode the cursor before sending (some upstreams double-encode).

is_linkboolean

Treat the value at cursor_path as a fully-qualified URL (or path) rather than an opaque token.

limit_data_typestring

Cast the limit value when sending it in the body.

Possible values:
numberstring
limit_keystring

Query/body key that holds the page size.

max_limitinteger

Maximum page size Truto will request.

prev_cursor_pathstring

Optional accessor that yields the previous-page cursor.

use_content_hashboolean

Detect loops by hashing each page's results. Only effective when cursor_path_object is body.

formatstring
Possible values:
cursor
link_header · 2 properties
configobject
5 properties
headersRecord<string, any>

Static or templated headers added to every paginated request.

ignore_limitboolean

Don't send limit_key even when the caller sets limit.

limit_keystring

Query key that holds the page size when the caller sets limit.

max_limitinteger

Maximum page size Truto will request.

page_keystring

Informational only; the actual cursor comes from the Link header.

formatstring
Possible values:
link_header
offset · 2 properties
configobject
10 properties
add_to_bodyboolean

Send pagination params in the request body instead of the query string.

add_to_queryboolean

Send pagination params in the query string.

default_offsetstring

Offset used for the first request (some APIs are 1-indexed).

headersRecord<string, any>

Static or templated headers added to every paginated request.

ignore_limitboolean

Drop limit_key from the URL after pagination is applied.

limit_keystring

Query/body key that holds the page size.

max_limitinteger

Maximum page size Truto will request.

offset_keystring

Query/body key that holds the offset.

total_pathstring

Optional dotted-path accessor into the response body that yields the total result count, used to stop paginating early.

use_content_hashboolean

Detect loops by hashing each page's results.

formatstring
Possible values:
offset
range · 2 properties
configobject
9 properties
add_to_bodyboolean

Send pagination params in the request body instead of the query string.

add_to_queryboolean

Send pagination params in the query string.

default_startstring

Start value used for the first request.

end_keystring

Query/body key that holds the end of the range (exclusive).

headersRecord<string, any>

Static or templated headers added to every paginated request.

ignore_limitboolean

Drop start_key, end_key, and limit from the URL after pagination is applied.

max_limitinteger

Maximum range size Truto will request.

start_keystring

Query/body key that holds the start of the range.

total_pathstring

Optional dotted-path accessor into the response body that yields the total result count, used to stop paginating early.

formatstring
Possible values:
range
dynamic · 2 properties
configobject
required
3 properties
get_cursor_from_response_expressionstring

JSONata expression evaluated after each response. Returns the next cursor (Truto then base64-encodes it) and optional loop-detection flags.

Input: IntegrationDynamicPaginationResponseContext. Output: IntegrationDynamicPaginationResponseResult.

get_initial_pagination_values_expressionstring

Optional JSONata expression evaluated before the first request. Use to seed pagination values (e.g. compute a default since window).

Input: IntegrationDynamicPaginationRequestContext. Output: IntegrationDynamicPaginationRequestResult.

get_pagination_values_expressionstring

JSONata expression evaluated before each subsequent request (when query.next_cursor is set). Mutates the URL/body/headers/query for the next page.

Input: IntegrationDynamicPaginationRequestContext with query.next_cursor decoded from base64. Output: IntegrationDynamicPaginationRequestResult.

formatstring
Possible values:
dynamic
queryRecord<string, any>

Default query-string params merged into every outbound request.

query_array_formatstring
Possible values:
commabracketsindicesrepeat
rate_limitobject

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

3 properties
is_rate_limitedstring

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
rate_limit_header_expressionstring

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` }
retry_after_header_expressionstring

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`)
resourcesRecord<string, any>

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_tagsRecord<string, any>

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

webhookobject

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.

3 properties
handle_verificationstring

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_transformstring

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).

signature_verificationobject

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

One of
hmac · 2 properties
configobject
required·

HMAC signature verification. Truto computes hmac(algorithm, secret, signed_string) and compares it (constant-time) with compare_with.

6 properties
algorithmstring

Hashing algorithm.

Example: sha256
compare_withstring

The signature value from the request to compare against. Usually a placeholder like {{headers.x-signature}}.

partsstring[]

Ordered list of IntegrationWebhookPayloadContext field names to concatenate as the signed string (e.g. ["raw_body"] or ["timestamp", "raw_body"]). Mutually exclusive with verification_content.

secretstring

Shared HMAC secret. Typically a placeholder like {{context.webhook_secret}} or {{environment_variables.WEBHOOK_SECRET_secret}}.

string_typestring

Output encoding for the computed digest.

Example: hex
verification_contentstring[]

Ordered list of placeholders to concatenate as the signed string (e.g. ["{{headers.x-timestamp}}", ".", "{{raw_body}}"]). Mutually exclusive with parts.

formatstring
Possible values:
hmac
basic · 2 properties
configobject
required·

HTTP Basic signature verification. Truto base64-encodes username:password and compares it with the second word of compare_with (i.e. Authorization: Basic <token>).

3 properties
compare_withstring

The full Authorization header value, e.g. {{headers.authorization}}.

passwordstring

Expected password. Supports placeholders.

usernamestring

Expected username. Supports placeholders.

formatstring
Possible values:
basic
bearer · 2 properties
configobject
required·

Bearer-token signature verification. Truto compares secret (constant-time) with the second word of compare_with (i.e. Authorization: Bearer <token>).

2 properties
compare_withstring

The full Authorization header value, e.g. {{headers.authorization}}.

secretstring

Expected bearer token. Supports placeholders.

formatstring
Possible values:
bearer
jwt · 2 properties
configobject
required·

JWT signature verification. Truto verifies compare_with is a valid JWT signed with secret (HS256 by default).

2 properties
compare_withstring

The JWT to verify, typically a placeholder like {{headers.authorization}} or {{body.token}}.

secretstring

Shared signing secret. Supports placeholders.

formatstring
Possible values:
jwt
created_atstring · date-time

The date and time when the integration was created.

Example: 2021-08-10T10:00:00.000Z
idstring · uuid

The ID of the integration.

Example: 4a4de828-f4db-4c9e-adfd-434e0864c3c7
installed_environmentstring[]

A list of environment IDs where this integration is installed.

is_betaboolean

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

Example: false
namestring

The name of the integration.

Example: zendesk
sharingstring

The sharing policy of the integration.

Example: allow
Possible values:
allowaskdeny
teamobject
10 properties
allow_impersonationboolean

Whether the team allows impersonation.

Example: false
created_atstring · date-time

The date and time when the team was created.

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

The domain of the team.

Example: example.com
idstring · uuid

The ID of the team.

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

Whether the team is verified or not.

Example: true
is_white_labelboolean

Whether the team is white-labeled or not.

Example: false
logostring

The URL of the team's logo.

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

The name of the team.

Example: My Awesome Team
tos_linkstring

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

Example: https://example.com/tos
updated_atstring · date-time

The date and time when the team was last updated.

Example: 2021-08-10T10:00:00.000Z
team_idstring · uuid

The ID of the team that owns this integration.

Example: 05daecaf-4365-42e8-8370-8127de5dd717
updated_atstring · date-time

The date and time when the integration was last updated.

Example: 2021-08-10T10:00:00.000Z
integration_idstring · uuid

The ID of the integration this environment integration references.

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

Whether this integration is enabled in the environment.

Example: true
overrideobject

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

actionsRecord<string, any>
authorizationobject

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.

One of
bearer · 2 properties
configobject
required
1 property
valuestring

The bearer token. Almost always a placeholder like {{oauth.token.access_token}} (OAuth2) or {{api_key}} (api-key fields).

Example: {{oauth.token.access_token}}
formatstring
Possible values:
bearer
basic · 2 properties
configobject
2 properties
passwordstring

Password, supports placeholders.

Example: {{client_secret}}
usernamestring

Username, supports placeholders (e.g. {{api_key}} for vendors that pass the API key as the username).

Example: {{client_id}}
formatstring
Possible values:
basic
header · 2 properties
configobject
2 properties
expressionstring

JSONata expression that fully constructs the outgoing request. Use for advanced cases (request signing, dynamic URL rewrites).

Input: IntegrationHeaderAuthorizationContext. Output: IntegrationHeaderAuthorizationResult (must contain url and requestOptions).

headersRecord<string, any>

Map of header name → value. Values support placeholders (e.g. { "X-API-Key": "{{api_key}}" }).

Example: {"X-API-Key":"{{api_key}}","X-Account-Id":"{{account_id}}"}
formatstring
Possible values:
header
base_urlstring
credentialsobject | Record<string, any>
descriptionstring

Environment-specific description shown in the catalog.

environment_variablesRecord<string, any>

Free-form key/value pairs available to JSONata as {{env.<key>}} for this integration in this environment. Values can be of any type (string, number, boolean, object, array).

error_expressionstring
headersRecord<string, any>
iconstring
labelstring
logostring
paginationobject

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

One of
page · 2 properties
configobject

Page-number pagination options. All fields optional; defaults shown.

9 properties
add_to_bodyboolean

Add pagination keys to the request body instead of the query string.

add_to_queryboolean

Add pagination keys to the query string. Defaults to true when add_to_body is false.

headersRecord<string, any>

Static or templated headers added to every paginated request. Templated against the request query plus a synthetic limit.

ignore_limitboolean

Drop the limit_key from the URL after pagination is applied (for APIs that 400 on it).

limit_keystring

Query/body key that holds the page size.

max_limitinteger

Maximum page size Truto will request, regardless of the caller's limit.

page_keystring

Query/body key that holds the page number.

starting_pagestring

Page number used for the first page (some APIs are 0-indexed).

use_content_hashboolean

Stop paginating when consecutive pages return identical results (loop detection). Defaults to true.

formatstring
Possible values:
page
cursor · 2 properties
configobject
required·

Cursor pagination options.

17 properties
add_to_bodyboolean

Send the cursor in the request body instead of the URL.

add_to_queryboolean

Add the cursor to the query string.

allow_empty_page_cursorboolean

Don't treat an empty cursor as the end of pagination.

cursor_keystring

Query/body key Truto uses to send the cursor on the next request.

cursor_pathstring

Dotted-path accessor into the response body (or headers, when cursor_path_object: header) that yields the next cursor.

Example: data.meta.next_cursor
cursor_path_objectstring

Where to read cursor_path from.

Possible values:
bodyheader
has_next_pathstring

Optional accessor that returns a truthy/"true"/"false" value indicating whether more pages exist.

headersRecord<string, any>

Static or templated headers added to every paginated request. Templated against the request query plus a synthetic limit.

ignore_limit_in_paginationboolean

Don't re-send limit_key after the first page (for APIs that reject it on subsequent calls).

include_pathboolean

When is_link is true, also overwrite the request path with the link's path (not just the query string).

is_cursor_url_encodedboolean

URL-decode the cursor before sending (some upstreams double-encode).

is_linkboolean

Treat the value at cursor_path as a fully-qualified URL (or path) rather than an opaque token.

limit_data_typestring

Cast the limit value when sending it in the body.

Possible values:
numberstring
limit_keystring

Query/body key that holds the page size.

max_limitinteger

Maximum page size Truto will request.

prev_cursor_pathstring

Optional accessor that yields the previous-page cursor.

use_content_hashboolean

Detect loops by hashing each page's results. Only effective when cursor_path_object is body.

formatstring
Possible values:
cursor
link_header · 2 properties
configobject
5 properties
headersRecord<string, any>

Static or templated headers added to every paginated request.

ignore_limitboolean

Don't send limit_key even when the caller sets limit.

limit_keystring

Query key that holds the page size when the caller sets limit.

max_limitinteger

Maximum page size Truto will request.

page_keystring

Informational only; the actual cursor comes from the Link header.

formatstring
Possible values:
link_header
offset · 2 properties
configobject
10 properties
add_to_bodyboolean

Send pagination params in the request body instead of the query string.

add_to_queryboolean

Send pagination params in the query string.

default_offsetstring

Offset used for the first request (some APIs are 1-indexed).

headersRecord<string, any>

Static or templated headers added to every paginated request.

ignore_limitboolean

Drop limit_key from the URL after pagination is applied.

limit_keystring

Query/body key that holds the page size.

max_limitinteger

Maximum page size Truto will request.

offset_keystring

Query/body key that holds the offset.

total_pathstring

Optional dotted-path accessor into the response body that yields the total result count, used to stop paginating early.

use_content_hashboolean

Detect loops by hashing each page's results.

formatstring
Possible values:
offset
range · 2 properties
configobject
9 properties
add_to_bodyboolean

Send pagination params in the request body instead of the query string.

add_to_queryboolean

Send pagination params in the query string.

default_startstring

Start value used for the first request.

end_keystring

Query/body key that holds the end of the range (exclusive).

headersRecord<string, any>

Static or templated headers added to every paginated request.

ignore_limitboolean

Drop start_key, end_key, and limit from the URL after pagination is applied.

max_limitinteger

Maximum range size Truto will request.

start_keystring

Query/body key that holds the start of the range.

total_pathstring

Optional dotted-path accessor into the response body that yields the total result count, used to stop paginating early.

formatstring
Possible values:
range
dynamic · 2 properties
configobject
required
3 properties
get_cursor_from_response_expressionstring

JSONata expression evaluated after each response. Returns the next cursor (Truto then base64-encodes it) and optional loop-detection flags.

Input: IntegrationDynamicPaginationResponseContext. Output: IntegrationDynamicPaginationResponseResult.

get_initial_pagination_values_expressionstring

Optional JSONata expression evaluated before the first request. Use to seed pagination values (e.g. compute a default since window).

Input: IntegrationDynamicPaginationRequestContext. Output: IntegrationDynamicPaginationRequestResult.

get_pagination_values_expressionstring

JSONata expression evaluated before each subsequent request (when query.next_cursor is set). Mutates the URL/body/headers/query for the next page.

Input: IntegrationDynamicPaginationRequestContext with query.next_cursor decoded from base64. Output: IntegrationDynamicPaginationRequestResult.

formatstring
Possible values:
dynamic
queryRecord<string, any>
query_array_formatstring
Possible values:
commabracketsindicesrepeat
rate_limitobject

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

3 properties
is_rate_limitedstring

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
rate_limit_header_expressionstring

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` }
retry_after_header_expressionstring

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`)
resourcesRecord<string, any>
tagsstring[]

Environment-specific tags shown in the catalog.

tool_tagsRecord<string, any>
webhookobject

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.

3 properties
handle_verificationstring

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_transformstring

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).

signature_verificationobject

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

One of
hmac · 2 properties
configobject
required·

HMAC signature verification. Truto computes hmac(algorithm, secret, signed_string) and compares it (constant-time) with compare_with.

6 properties
algorithmstring

Hashing algorithm.

Example: sha256
compare_withstring

The signature value from the request to compare against. Usually a placeholder like {{headers.x-signature}}.

partsstring[]

Ordered list of IntegrationWebhookPayloadContext field names to concatenate as the signed string (e.g. ["raw_body"] or ["timestamp", "raw_body"]). Mutually exclusive with verification_content.

secretstring

Shared HMAC secret. Typically a placeholder like {{context.webhook_secret}} or {{environment_variables.WEBHOOK_SECRET_secret}}.

string_typestring

Output encoding for the computed digest.

Example: hex
verification_contentstring[]

Ordered list of placeholders to concatenate as the signed string (e.g. ["{{headers.x-timestamp}}", ".", "{{raw_body}}"]). Mutually exclusive with parts.

formatstring
Possible values:
hmac
basic · 2 properties
configobject
required·

HTTP Basic signature verification. Truto base64-encodes username:password and compares it with the second word of compare_with (i.e. Authorization: Basic <token>).

3 properties
compare_withstring

The full Authorization header value, e.g. {{headers.authorization}}.

passwordstring

Expected password. Supports placeholders.

usernamestring

Expected username. Supports placeholders.

formatstring
Possible values:
basic
bearer · 2 properties
configobject
required·

Bearer-token signature verification. Truto compares secret (constant-time) with the second word of compare_with (i.e. Authorization: Bearer <token>).

2 properties
compare_withstring

The full Authorization header value, e.g. {{headers.authorization}}.

secretstring

Expected bearer token. Supports placeholders.

formatstring
Possible values:
bearer
jwt · 2 properties
configobject
required·

JWT signature verification. Truto verifies compare_with is a valid JWT signed with secret (HS256 by default).

2 properties
compare_withstring

The JWT to verify, typically a placeholder like {{headers.authorization}} or {{body.token}}.

secretstring

Shared signing secret. Supports placeholders.

formatstring
Possible values:
jwt
show_in_catalogboolean

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

Example: true
updated_atstring · date-time

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

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