# Integrations Object

> Source: https://truto.one/docs/api-reference/admin/integrations/

Schema for the `Integrations` resource in **Admin API**.

## Properties

- **`id`** _(string)_
  The ID of the integration.
- **`name`** _(string)_
  The name of the integration.
- **`category`** _(string)_
  The category of the integration.
- **`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.
  - **`base_url`** _(string)_
    Default base URL prepended to every resource method's `path`.
  - **`label`** _(string)_
    Human-readable name shown in the Truto Dashboard and Link UI.
  - **`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)_
    Allowed: `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`** _(object)_
    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)_
    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**
      - **`format`** _(string)_
        Allowed: `bearer`
      - **`config`** _(object, required)_
    - **basic**
      - **`format`** _(string)_
        Allowed: `basic`
      - **`config`** _(object)_
    - **header**
      - **`format`** _(string)_
        Allowed: `header`
      - **`config`** _(object)_
  - **`pagination`** _(object)_
    Pagination strategy for an integration or a single resource method. The `format` discriminator selects which `config` shape applies.
    _One of:_
    - **page**
      - **`format`** _(string)_
        Allowed: `page`
      - **`config`** _(object)_
        Page-number pagination options. All fields optional; defaults shown.
    - **cursor**
      - **`format`** _(string)_
        Allowed: `cursor`
      - **`config`** _(object, required)_
        Cursor pagination options.
    - **link_header**
      - **`format`** _(string)_
        Allowed: `link_header`
      - **`config`** _(object)_
    - **offset**
      - **`format`** _(string)_
        Allowed: `offset`
      - **`config`** _(object)_
    - **range**
      - **`format`** _(string)_
        Allowed: `range`
      - **`config`** _(object)_
    - **dynamic**
      - **`format`** _(string)_
        Allowed: `dynamic`
      - **`config`** _(object, required)_
  - **`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.
    - **`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).
    - **`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`.
  - **`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. **Not** to be confused with `WebhookSchema` elsewhere in this spec, which describes Truto's _outbound_ webhook delivered to your application.
    - **`signature_verification`** _(object)_
      Strategy used to verify the webhook signature before accepting it. Runs **after** `payload_transform` and **after** `handle_verification` returns `{ type: 'payload' }`.
      _One of:_
      - **hmac**
        - **`format`** _(string)_
          Allowed: `hmac`
        - **`config`** _(object, required)_
          HMAC signature verification. Truto computes `hmac(algorithm, secret, signed_string)` and compares it (constant-time) with `compare_with`.
      - **basic**
        - **`format`** _(string)_
          Allowed: `basic`
        - **`config`** _(object, 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>`).
      - **bearer**
        - **`format`** _(string)_
          Allowed: `bearer`
        - **`config`** _(object, required)_
          Bearer-token signature verification. Truto compares `secret` (constant-time) with the second word of `compare_with` (i.e. `Authorization: Bearer <token>`).
      - **jwt**
        - **`format`** _(string)_
          Allowed: `jwt`
        - **`config`** _(object, required)_
          JWT signature verification. Truto verifies `compare_with` is a valid JWT signed with `secret` (HS256 by default).
    - **`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)_
    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)_
  The ID of the team that owns this integration.
- **`sharing`** _(string)_
  The sharing policy of the integration.
  Allowed: `allow`, `ask`, `deny`
- **`created_at`** _(string)_
  The date and time when the integration was created.
- **`updated_at`** _(string)_
  The date and time when the integration was last updated.
- **`installed_environment`** _(array<string>)_
  A list of environment IDs where this integration is installed.
- **`team`** _(object)_
  - **`id`** _(string)_
    The ID of the team.
  - **`name`** _(string)_
    The name of the team.
  - **`domain`** _(string)_
    The domain of the team.
  - **`logo`** _(string)_
    The URL of the team's logo.
  - **`is_verified`** _(boolean)_
    Whether the team is verified or not.
  - **`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.
  - **`allow_impersonation`** _(boolean)_
    Whether the team allows impersonation.
  - **`created_at`** _(string)_
    The date and time when the team was created.
  - **`updated_at`** _(string)_
    The date and time when the team was last updated.

## Methods

- [GET /integration](/docs/api-reference/admin/integrations/list) — List integrations
- [POST /integration](/docs/api-reference/admin/integrations/create) — Create integration
- [GET /integrations/{id}](/docs/api-reference/admin/integrations/get) — Get integration
- [PATCH /integrations/{id}](/docs/api-reference/admin/integrations/update) — Update integration
- [DELETE /integrations/{id}](/docs/api-reference/admin/integrations/delete) — Delete integration
- [GET /integration/{id}/tools](/docs/api-reference/admin/integrations/tools) — (Deprecated) Get integration tools
- [GET /integration/{id}/unified-apis](/docs/api-reference/admin/integrations/unified-apis) — (Deprecated) Get unified APIs supported by an integration
- [GET /integration/{id}/capabilities](/docs/api-reference/admin/integrations/capabilities) — Get integration capabilities (proxy + unified + auth)