Connecting your Worker to tools: integrations

An integration connects your Worker to a third-party service (Slack, HubSpot, GitHub, Pega…) so it can read and act there. This article explains where to find integrations, the different ways to connect, and the classic pitfalls that make things "not show up" or "not work".

The key idea: an integration is like handing your Worker a keyring. Once it has the key, it knows how to open the right door (via the discover mechanism — see the Behavior Studio article).

1. Where it happens

• Open the Worker's page → Integrations tab
• There you'll find the catalog (everything available, grouped by category) and your active connections

The categories

Integrations are sorted into broad families:

2. The different ways to connect

Not all integrations connect the same way. Here are the main cases, from a user's point of view:

a) OAuth (the most common)

You click Connect, a window of the service opens, you sign in and authorize the access. No key to copy. Examples: Slack, Gmail, Notion, Linear, Stripe, LinkedIn, GitHub…

b) API key

You click Connect, a dialog asks you to paste an API key generated at the provider. Examples: Apollo, Hunter, Grafana, PostHog, Pappers…

⚠️ No validation at entry. The key is stored as-is; its validity is only tested when the Worker uses it. A "connected" card can therefore hide an invalid key — test it by asking the Worker to perform an action.

c) OAuth "BYOK" (Bring Your Own Key)

The service runs on your instance or requires your own OAuth application. You additionally provide an instance URL and/or a Client ID + Client Secret. Examples: Pega (instance URL + client id/secret), Salesforce, Affinity, DocuSign. → see the dedicated Integrating Pega article.

d) Special cases

• Phone (Telegram in personal-account mode): number + SMS code.
• No credentials (Excalidraw, Data.gouv): a simple switch, nothing to connect.

3. Connect, enable, disconnect

The toggle (active/inactive)

Once connected, each integration has a toggle:

• On → the Worker can use it
• Off → the connection is kept but the Worker no longer uses it (soft disable)

The masked key

For API keys, only the first and last characters stay visible (e.g. sk_abc123…xyz).

Disconnect

The trash icon permanently deletes the credentials. The card goes back to "Not authorized".

4. Personal or shared by the team?

• Personal credentials (default): each user connects their own account. Your HubSpot connection is not your colleague's.
• Organization-level credentials: an admin configures a shared application (Client ID/Secret) that the whole organization reuses. This is what enables team "BYOK", sometimes restricted to specific teams.

Who can connect? Changes go through the Worker's manager. Organization credentials are managed in the admin space.

5. The classic pitfalls

1. "I can't see the integration." Some integrations exist but are not listed in the catalog (intentionally hidden or not yet published — this is the case for Telegram, WhatsApp, or brand-new integrations). If an integration is defined but missing from the catalog, it won't appear until the catalog is updated.

2. "It says connected but it doesn't work." For API keys, there's no validation at entry: a wrong key goes unnoticed until first use. Also check that the toggle is on.

3. "OAuth fails (redirect_uri mismatch)." In BYOK mode, your OAuth application must declare exactly the right redirect URL. A mistyped URL makes the connection fail.

4. "It asks me for an instance URL." Multi-instance services (Salesforce, Pega…) need your instance origin (e.g. https://acme.pega.com). A typo fails silently.

5. "Paid plan required." Some services restrict API access to their paid tiers (e.g. Apollo). Without a suitable plan, the key will be rejected at use time.

What's next?

Once the integration is active, you have nothing else to do: when a task requires it, the Worker activates the integration on the fly (the discover mechanism) and calls the right tools. → see the Skills, Behavior Studio & Discover article.