> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt > Use this file to discover all available pages before exploring further. # Integrations > Connected third-party systems: Unified.to integrations managed from the CLI and catalog integrations connected in the dashboard An integration is a connection between an [agent](/concepts/agents) and a third-party system, with the credential held by the platform. Two families exist. Unified.to integrations cover several hundred SaaS products and are connected and managed with `lua integrations`; catalog integrations (Shopify, WooCommerce, Square, and SimplyBook.me) are connected from the admin dashboard and come with purpose-built commerce and booking tools. Integrations exist so the agent can act in systems you already use without you writing, storing, or seeing a credential. ## How an integration is connected ### Unified.to integrations `lua integrations available` lists the integration types by category, and `lua integrations info ` shows one type's auth methods, scopes, and events. `lua integrations connect --integration ` starts a connection: the CLI opens the Unified.to authorization page in your browser and waits up to five minutes on a local callback. OAuth integrations sign in there; token-based ones take their keys on that page too, never in the terminal. `--scopes all` or a comma-separated list sets what the connection may do, and `--triggers ` subscribes to events in the same step. A connection has an owner. With the default `--scope agent` it belongs to this agent and goes when the agent goes. With `--scope user` it is a personal connection: every private agent you created can use it, and publishing an agent removes its access; the agent-only options (`--triggers`, `--hook-url`, `--custom-webhook`, `--account-label`, `--hide-sensitive`) are refused for personal connections. Several accounts of one integration type can be connected, told apart by their account label, and `--connection-id ` names one when you `update`, `disconnect`, or `convert`. `lua integrations update --connection-id ` re-authorizes in place: the connection keeps its ID and its event subscriptions, and if authorization fails nothing changes. `lua integrations list --scope all` shows what is connected and its status. A connection provides three things: * Tools. Finalizing an agent connection creates an MCP server named after the integration type and activates it, so the agent has the integration's operations on its next turn; `lua integrations mcp activate|deactivate --connection ` activates or deactivates it, and `lua integrations mcp list` shows it. A personal connection is mounted on each of your private agents instead. * Events. `lua integrations webhooks create --connection --object --event created|updated|deleted` subscribes to an event such as `task_task.created` or `task_task.updated`; `lua integrations webhooks events --integration ` lists what an integration emits. Each delivery wakes the agent in a background turn carrying the payload, on the channel `integration:`; payloads over 50,000 characters are truncated. Delivery is at most once: the platform acknowledges the event on receipt, retries nothing, and deduplicates nothing, so a provider that redelivers an event wakes the agent again. To run your own code instead, pass `--hook-url` with a [webhook](/concepts/webhooks) or [trigger](/concepts/triggers) URL. For integrations without push, the provider polls at `--interval ` and the events arrive the same way. Subscriptions can be paused and resumed per webhook or per connection. * Raw API access. `Integrations.passthrough(type, { method, path, query?, data?, headers? })` calls the provider's REST API through the agent's own connection and returns `{ status, headers, data }`. Provider errors, a provider's own 429 included, come back in `status` rather than as exceptions, and the platform adds the authorization itself. When the agent has no connection of that type or passthrough is disabled for the integration, the call throws an `IntegrationPassthroughError`. The platform allows 120 passthrough calls per minute per agent, counting calls from your code and from the model's `_passthrough` tool alike; above that the call throws with status 429 and code `passthrough_rate_limited` and no retry-after value, so wait before calling again. Every passthrough call is logged by the platform for support and abuse review, never with bodies; the log isn't readable through the CLI or API. ```ts src/skills/tools/GetPullRequestDiffTool.ts theme={null} import { LuaTool, Integrations } from 'lua-cli'; import { z } from 'zod'; export default class GetPullRequestDiffTool implements LuaTool { name = 'get_pull_request_diff'; description = 'Fetch the diff of a pull request in the connected GitHub account'; inputSchema = z.object({ repo: z.string(), number: z.number() }); async execute(input: z.infer) { const res = await Integrations.passthrough('github', { method: 'GET', path: `repos/${input.repo}/pulls/${input.number}`, headers: { Accept: 'application/vnd.github.diff' }, }); if (res.status !== 200) throw new Error(`github ${res.status}`); return res.data; } } ``` ### Catalog integrations Shopify, WooCommerce, Square, and SimplyBook.me are connected from the admin dashboard, not the CLI; none appears in `lua integrations`. Shopify and WooCommerce sync the store's catalog into the agent's `Products`, `Baskets`, and `Orders` data, and the agent gets tools to search products, look one up by ID, manage a basket, and check out on the store; Shopify adds lookup by SKU and a stock check, keeps the catalog current through product webhooks, and can embed the web widget on the storefront, while WooCommerce adds category browsing. Square adds catalog search, appointment booking, customers, orders, and Square-hosted payment links. SimplyBook.me adds services, staff, the first available day, time slots, and creating or canceling a booking. Shopify and WooCommerce also appear as Unified.to integration types (WooCommerce with token auth, Shopify with OAuth or a token); the catalog integration is the one that fills `Products` and `Baskets`. ## Integrations and MCP servers A Unified.to integration's tools arrive as an [MCP server](/concepts/mcp-servers) the platform provisions; a `LuaMCPServer` you declare is one you or a vendor host, with headers you manage. Prefer the integration whenever the system is in `lua integrations available`: authentication, scopes, and events are handled, and there is nothing to keep secret. Write a `LuaMCPServer` for a server the catalog does not cover, and a [tool](/concepts/skills-and-tools) with `fetch` for an internal API. ## When to use it * The agent must read or write a known SaaS: connect it and use the provisioned tools. * The agent should react when something changes there: subscribe to the event, then route it to the agent, a webhook, or a workflow. * You need an endpoint the integration's tools do not expose, or a raw response body such as a diff: `Integrations.passthrough` inside a tool. * The shop runs on Shopify or WooCommerce: connect it in the admin dashboard and let the integration own the catalog and basket. * Don't hand-write tools or a `LuaMCPServer` for a system the catalog covers. ## Limits | Item | Value | | ------------------------------------ | -------------------------------------------------------- | | Authorization wait | 5 minutes | | Event payload delivered to the agent | 50,000 characters, then truncated | | Event delivery | At most once; no retry, no deduplication | | Passthrough | Provider status relayed; relay failures throw | | Passthrough calls | 120 per minute per agent; 429 `passthrough_rate_limited` | | Personal connections | Private agents you created; agent-only options refused | ## Next steps Connect, pick scopes, and verify the tools in a chat. Subscribe to events and route them to code. Call the provider's API from a tool. Every action and flag.