Import integrated account into Truto

Please use this endpoint only for importing existing app credentials into Truto. To connect new Integrated accounts, please use the Link token approach.

Endpoint

http

POST /integrated-account

Request Body

tenant_id

string

The ID of the tenant.

Example: acme-1

environment_integration_id

string

The ID of the environment integration (installed integration).

Example: b179ad55-db02-4bd4-b7a4-d2c173eee9ae

context

object

The context of the integrated account.

You can find these in the Variables section of an integrated account in the Truto UI.

For creating an integrated account with authentication_type oauth2, oauth2_client_credentials and keka_oauth, set the oauth object to

  { 
    "token": { 
      "access_token": "<token_value", 
      "refresh_token": "<if_available>", 
      "expires_in": <value> 
    } 
  }

For api_key, please refer the fields section of credentials object of the integration.

Example:

{
  "oauth": {
    "token": {
      "access_token": "secret_foo_bar",
      "refresh_token": "refresh_foo_bar",
      "expires_in": 3600
    }
  }
}

authentication_method

string

Type of authentication used.

All possible enum values:

oauth2
api_key
oauth2_client_credentials
keka_oauth

region

string

The region where the integrated account is placed.

All possible enum values:

wnam
enam
apac
eu

Example: wnam

Response Body

string · uuid

The ID of the integrated account.

Example: 1ba1f401-7183-47c5-9e39-e8e257e3c795

tenant_id

string

The ID of the tenant.

Example: acme-1

environment_integration_id

string

The ID of the environment integration (installed integration).

Example: b179ad55-db02-4bd4-b7a4-d2c173eee9ae

context

object

The context of the integrated account. You can find these in the Variables section of an integrated account in the Truto UI.

Example:

{
  "zendesk_subdomain": "truto"
}

status

string

Status of the integrated account.

active - Everything is fine and the account should work
connecting - Post install and validation steps are being run
post_install_error - There was an error while running post install steps
validation_error - There was an error while running validation steps
needs_reauth - There was an error while refreshing the credentials in case of OAuth authentication or the credentials are no longer valid in other authentication methods. The integrated account needs to be reauthorized.

All possible enum values:

active
connecting
post_install_error
validation_error
needs_reauth

last_error

string

The last error that occurred while running the post install or validation steps.

last_action_result

object

The results of the post install and validation steps that ran on the integrated account.

created_at

string · date-time

The date and time when the integrated account was created.

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

updated_at

string · date-time

The date and time when the integrated account was last updated.

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

is_sandbox

boolean

Whether the integrated account is in sandbox mode or not. Sandbox integrated accounts do not allow any "write" operations.

authentication_method

string

Type of authentication used.

All possible enum values:

oauth2
api_key
oauth2_client_credentials
keka_oauth

region

string

The region where the integrated account is placed.

All possible enum values:

wnam
enam
apac
eu

Example: wnam

environment_id

string · uuid

The ID of the environment this integrated account belongs to.

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

integration

object

The integration associated with this integrated account.

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": {
            "token": "{{oauth.token.access_token}}"
          }
        }
      }
    }
  },
  "webhook": {
    "signature_verification": {
      "format": "HMAC-SHA256",
      "config": {
        "secret": "your-webhook-secret",
        "algorithm": "sha256",
        "parts": [
          "header",
          "body"
        ]
      }
    },
    "handle_verification": "verify_webhook_signature"
  },
  "error_expression": "{{response.error}}"
}

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

object

REQUIRED ·

How Truto applies the credential to outbound HTTP requests.

format

string

The authorization strategy. bearer adds an Authorization: Bearer <token> header, basic does HTTP Basic with username/password, header lets you fully control the header name and value template.

All possible enum values:

basic
bearer
header

Example: bearer

config

object

Free-form config keyed off format. For bearer, typically { token: "{{credentials.access_token}}" }. For header, typically { name: "X-API-Key", value: "{{credentials.api_key}}" }. For basic, typically { username: "...", password: "..." }.

pagination

object

REQUIRED ·

Pagination strategy for an integration or a single resource method.

format

string

The pagination strategy.

All possible enum values:

page
cursor
link_header
offset
range
dynamic

Example: cursor

config

object

Free-form config keyed off format. The shape depends on the strategy (e.g. page/limit_key for page; cursor_path/cursor_key for cursor; next_url_path for link_header).

rate_limit

object

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

is_rate_limited

string

JSONata expression returning true when the response indicates rate-limiting (e.g. status_code = 429).

Example: status_code = 429

retry_after_header_expression

string

JSONata expression returning the seconds-to-wait (or absolute timestamp) when rate-limited.

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

rate_limit_header_expression

string

JSONata expression returning the remaining quota in the current window (used for proactive backoff).

Example: $number(headers.`x-ratelimit-remaining`)

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

How Truto receives and verifies inbound webhooks for this integration. Mirrors WebhookSchema in src/integration/integrationSchema.ts. Not to be confused with WebhookSchema in this file, which is Truto's outbound webhook to your application.

signature_verification

object

REQUIRED ·

Strategy used to verify the webhook signature before accepting it.

format

string

Named verification strategy (e.g. hmac, basic, jwt, clerk, etc.). See src/integration/integrationConfig/*.json for the full list.

config

object

Configuration for the named signature_verification.format strategy. Different strategies use different subsets of these fields.

username

string

Used by HTTP-basic verification.

password

string

Used by HTTP-basic verification.

parts

string[]

Ordered list of payload pieces concatenated before hashing (e.g. ["timestamp", "body"]).

verification_content

string[]

Header/path/body lookups concatenated to form the signed string for some strategies.

secret

string

Shared HMAC secret. Often a templated reference like {{integration.config.webhook_secret}}.

string_type

string

How the signed string is encoded before hashing (e.g. base64, hex).

algorithm

string

Hashing algorithm (e.g. sha256, sha1).

compare_with

string

Where to find the signature on the request (typically a header name).

context_lookup_field_name

string

Field name used to look up an integrated account when the webhook isn't routed by URL token.

context_lookup_field_value

string

JSONata expression that produces the lookup value from the webhook payload.

handle_verification

string

JSONata expression evaluated when the platform receives a verification (handshake) ping. Should return either the value to echo back or a { status, body, headers } shape.

payload_transform

string

JSONata expression that transforms the raw webhook payload into the canonical { event_type, integrated_account_id, payload } shape Truto fans out.

error_expression

string

Integration-wide JSONata expression that detects errors. Overridden by per-method error_expression when set.

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

object_store_context_fields

string[]

The list of context fields that are stored in the object store.