Connectors

Connectors let bots work in other apps (Gmail, Slack, Notion, GitHub and 1,600+ more) using each person's own account. Credentials stay with the integration provider: Lex stores only a reference and checks policy on every action.

Find a connector

GET /catalog/connectors?q=gmail&limit=30

Each item has slug, name, logo, categories, toolsCount and usage.connected (whether you have connected it). GET /catalog/connectors/{slug} adds your connections and the full list of actions with how each one runs.

Connect an account

POST /integrations/{slug}/connect
x-lex-client: my-app
Content-Type: application/json

{ "returnTo": "/b/bot_123" }

The answer depends on how the app signs in:

status	What to do
requires_user_authorization	Send the user to authorizationUrl. After signing in they come back to returnTo (a path on the Lex app). Then call POST /integrations/connections/{connectionId}/sync to confirm.
requires_credentials	Ask for the fields in fields (e.g. an API key) and call connect again with { "credentials": { "generic_api_key": "…" } }. Values go straight to the provider and are never shown again.
connected	Done.
pending	The provider hasn't confirmed yet; sync again shortly.

returnTo must be a path that starts with /; full URLs are rejected. A person can connect several accounts of the same app; set label to tell them apart.

Manage connections

GET /integrations/connections	Your connections and their status
PATCH /integrations/connections/{id}	Rename (displayLabel) or make it the default (isDefault: true)
POST /integrations/connections/{id}/sync	Re-check with the provider
DELETE /integrations/connections/{id}	Disconnect
PUT /connector-connections/{id}/bots	Let a bot use this connection: { "botId": "…" }
DELETE /connector-connections/{id}/bots/{botId}	Take that access away

A bot can only use connections that have been granted to it. Chats without a bot can use all of your connections.

Policies

Workspace owners and admins decide what each connector may do:

PUT /integrations/policies/gmail
x-lex-client: my-app
Content-Type: application/json

{
  "enabled": true,
  "deniedTools": ["GMAIL_DELETE_MESSAGE"],
  "autoRunTools": ["GMAIL_CREATE_EMAIL_DRAFT"],
  "askTools": ["GMAIL_FETCH_EMAILS"]
}

Field	Effect
enabled	false turns the connector off for everyone in the workspace
deniedTools	Never run
askTools	Always ask first, even reads
autoRunTools	Write tools that may run without asking (high-impact tools still ask)
writeRequiresApproval	Ask before any write tool (default true)
allowedTools	If set, every tool not on the list is blocked

Without a policy, a connector is on, reads run on their own and everything else asks first.

Run a tool directly

POST /integrations/tools/GMAIL_FETCH_EMAILS/execute
x-lex-client: my-app
Content-Type: application/json

{ "arguments": { "max_results": 5 }, "idempotencyKey": "inbox-2026-10-22" }

Lex picks your default connection for the app; you can't point a tool at someone else's account. Arguments are validated against the tool's schema before anything runs, and secrets in the output are redacted. Write tools need an approval.

GET /integrations/tools/search?q=send email finds tools across the connectors you can use.