Integrations

Connect workspaces to REST APIs with managed credentials, endpoint definitions, and isolated endpoint tests.

Integrations connect a workspace to external REST APIs such as CRMs, scheduling systems, and custom backends. The Platform API integration surface manages the connection, credential configuration, endpoint definitions, and isolated endpoint tests.

For the exact operation list, request/response schemas, filters, and pagination parameters, use the Integrations API reference. This guide focuses on modeling and design choices.

Key Concepts

• Connection: a REST base URL plus optional authentication configuration.
• Endpoint definitions: child resources that describe callable HTTP operations, input schemas, path/query/body mapping, and response handling.
• Endpoint IDs: management operations address endpoint child resources by ID. Human-readable endpoint names remain useful for skill configuration and review.
• Endpoint testing: test one endpoint with sample parameters before exposing it to a skill or conversation flow.
• Approval policies: integrations can require human approval before write operations, or before every endpoint call, depending on workflow risk.
• Managed connectors: EHR/FHIR, desktop, and MCP-style capabilities are handled by connector, data-source, or system-provisioned infrastructure rather than the public REST integrations CRUD surface.

Authentication

The auth object's type field selects one of the supported credential schemes. Inline secret values are provisioned to secure storage on creation and never returned in API responses.

auth.type	Use case
static_header	API key or static bearer token sent in a fixed header. For a bearer token, set header_name to Authorization and store Bearer <token> as the secret.
oauth2_client_credentials	OAuth2 client-credentials grant.
oauth2_jwt_bearer	OAuth2 JWT-bearer grant.
custom_token_exchange	Per-request bearer token minted from a workspace secret plus dynamic identifiers.

The inline secret is a single sibling secret_value field on the create/update body; there are no per-type *_value fields. SMART on FHIR Backend Services authentication is handled at the connector and data-source layer, not as an integration auth type.

Custom Token Exchange

custom_token_exchange covers third-party APIs that require a per-call bearer token derived from a workspace-level secret plus one or more request-scoped identifiers. For example, an integration can combine a workspace credential with a per-end-user identifier to mint a user-scoped bearer token.

There is no token caching; every call mints a fresh token. The integration-level secret_value is referenced in exchange templates with the {secret} placeholder.

When the token exchange needs the authenticated external-user identity, bind that parameter with auth.identity_bindings so the value is resolved from verified session context instead of model-supplied tool input. See External User Subject-Key Binding.

Endpoint Definitions

Define endpoints as child resources on the integration. Each endpoint describes one callable operation:

• HTTP method and path relative to the integration base URL.
• Input schema for the arguments callers may provide.
• Mapping from those arguments into path parameters, query parameters, headers, and request body.
• Optional response shaping so the agent sees only the useful result.

Create or update endpoints before wiring them into a skill. Use endpoint tests to validate auth, parameter mapping, response shape, and upstream error behavior without starting a live conversation.

Approval Policies

Use approval policies when an integration call can create, update, delete, or otherwise affect external records. A write-gated policy routes write operations through human approval before execution; an all-gated policy requires approval for every endpoint call. Treat missing approval policy values on older integrations as no approval required.

See Approval-Gated Integration Writes for the approval lifecycle, channel coverage, and guidance on deciding what to gate.

Usage with Skills

Skills reference integration endpoints through integration_tools, giving the skill's LLM access to selected external API operations during execution:

{
  "slug": "check-appointments",
  "integration_tools": [
    { "integration": "scheduling", "endpoint": "list_slots" }
  ]
}

Keep endpoint input schemas narrow and explicit. The agent uses the schema to decide when to call a tool and how to populate arguments; overly broad schemas increase the chance of malformed upstream requests.

API Reference

• Integrations