Connect an integration

ModuleX connects to 175 services — GitHub, Slack, Gmail, Notion, Salesforce, and many more — so your workflows can act on them: open an issue, send a message, read a row, create a contact. This guide walks you through it end to end: connect a service once, then call one of its actions from a tool node in a workflow. You connect a service once, for your whole organization. After that, every workflow and the Assistant can use it. For the bigger picture of what integrations are, start with the integrations overview.

Before you start

A few things make this go smoothly.

An account in an organization

Integrations are connected per organization, not per person. Make sure you are working in the right one — the organization switcher is in the app header.

The owner or admin role

Only an owner or an admin can connect and manage credentials for an organization. If you do not see the connect controls, ask an owner or admin to connect the service. See roles & permissions.

An account on the service

For most services you sign in with your existing account during the connect step. Some services need an API key instead — you can paste one in.

You do not have to connect everything yourself. ModuleX offers managed keys for many services — see Three ways to connect below — so you can try a tool before bringing your own account.

How connecting works

Connecting a service stores a credential: an encrypted record that links your organization to that service. You create it once; ModuleX encrypts it, and uses it automatically every time a workflow or the Assistant calls one of that service’s tools. You never paste a secret into a workflow. Behind the scenes there are a few canonical terms worth knowing.

Integration vs. tool

An integration is the connection to one service, for example GitHub. Each integration exposes many tools — the individual actions you can call, such as github.create_issue or github.list_repositories. ModuleX has 175 integrations and 600+ tools in total. Browse them in the catalog.

Credential

A credential is the encrypted, organization-scoped record that proves your identity to a service. One integration can hold more than one credential — for example a production GitHub and a test GitHub — and you mark one as the default.

Default credential

When a tool runs and you have not picked a specific credential, ModuleX uses the one you marked as default for that integration. Set or change the default any time from managing credentials.

Three ways to connect

A service tells ModuleX which methods it supports. Most integrations offer one or more of these three. The connect screen shows you only the options that apply.

OAuth (recommended)

Sign in to the service and grant access — no copying secrets. This is the smoothest path and is covered step by step below. The technical details live in integration authentication.

Your own key (BYOK)

Paste an API key or token you already have from the service. Usage is billed directly by the provider, with no ModuleX markup.

ModuleX-managed key

For supported services, use a key ModuleX provides — nothing to set up. Managed usage is metered in credits.

Connect a service with OAuth

OAuth lets you connect by signing in to the service, instead of handling secrets yourself. The example below uses GitHub; the steps are the same for any service that offers OAuth.

Open the integrations catalog

In the app, go to your organization settings and open Browse integrations. Find the service — search by name or filter by category — and open it. See the integrations overview for a tour of the catalog.

Start the connection

Choose Add credential, then pick OAuth as the method. Give the credential a clear name — for example Production GitHub — so you can tell it apart later if you connect more than one account. Turning on Make default lets workflows use it automatically.

ModuleX sends you to the service’s own sign-in and consent screen. Review the access it asks for, then approve. This grant uses OAuth2 with PKCE, an industry-standard secure flow — you stay on the service’s site to sign in, and ModuleX never sees your password.

Return to ModuleX

After you approve, the service sends you back to ModuleX and the credential is saved automatically. You will see a success message, and the integration now shows as connected. That is it — the service is ready to use across your workflows and the Assistant.

The integration appears under your connected credentials with a name, the OAuth method, and a default badge if you set one. You are ready to use the tool in a workflow.

Connect with your own key instead

If a service does not offer OAuth, or you would rather bring your own account, choose API key (or bearer token) on the same connect screen and paste the value from the service. ModuleX checks the key before saving so you catch a typo early. The secret is encrypted at rest and never shown again in full — only a masked preview. For the full list of methods a service can offer and how each is stored and resolved, see integration authentication.

Use the tool in a workflow

With the service connected, you can call its actions from a workflow. The unit that does this is the tool node — it runs one action, with parameters you control, and writes the result into your run so later steps can use it.

Add a tool node

Open a workflow in the workflow builder and add a tool node to the canvas.

Pick the integration and action

In the node’s detail panel, pick the connected integration (for example GitHub) and then the action you want (for example create_issue). ModuleX shows the credential it will use — the default for that integration unless you choose another.

Fill in the parameters

Enter the action’s inputs — for create_issue, that is the repository, the title, and the body. You can type fixed values, or pull a value from an earlier step using a {{node_id.field}} reference. See variables & references for the reference syntax.

Run and check the result

Run the workflow. The tool node calls the service, and the action’s result is written into run state under the node’s own id, ready for the next step. For how runs stream and how failures surface, see running workflows.

Want a step where the AI decides which tools to call, rather than a fixed action? Use the agent node, or let the Assistant use your connected tools directly in chat — no workflow required.

Connect a service from code

You can also create a credential through the API. Authenticate every request with your API key as Authorization: Bearer mx_live_… plus the X-Organization-ID header for your organization. The example below creates an API-key credential for a service; the response masks the secret.

OAuth connections involve a browser sign-in step, so they are made in the app, not from a single API call. Use the app’s connect flow for OAuth, and the API for key-based credentials.

curl -X POST https://api.modulex.dev/credentials \
  -H "Authorization: Bearer mx_live_yourkey" \
  -H "X-Organization-ID: 8f2b1c4e-1a2b-4c3d-9e8f-7a6b5c4d3e2f" \
  -H "Content-Type: application/json" \
  -d '{
        "integration_name": "tavily",
        "display_name": "Production Tavily",
        "make_default": true,
        "auth_data": { "api_key": "tvly-your-service-key" }
      }'

import httpx

resp = httpx.post(
    "https://api.modulex.dev/credentials",
    headers={
        "Authorization": "Bearer mx_live_yourkey",
        "X-Organization-ID": "8f2b1c4e-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    },
    json={
        "integration_name": "tavily",
        "display_name": "Production Tavily",
        "make_default": True,
        "auth_data": {"api_key": "tvly-your-service-key"},
    },
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.modulex.dev/credentials", {
  method: "POST",
  headers: {
    Authorization: "Bearer mx_live_yourkey",
    "X-Organization-ID": "8f2b1c4e-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    integration_name: "tavily",
    display_name: "Production Tavily",
    make_default: true,
    auth_data: { api_key: "tvly-your-service-key" },
  }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

Creating and managing credentials requires the owner or admin role. A request from a non-admin member is rejected. ModuleX never reads the organization from the request body — it always comes from the X-Organization-ID header.

For the full credential API — listing, setting a default, testing, and deleting — see managing credentials.

Keep a connection working

A connection lasts until the service’s access expires or is revoked. For OAuth connections, ModuleX refreshes access automatically in the background as tokens near expiry, so most connections keep working without any action from you.

If an OAuth connection stops working — for example because access was revoked on the service — reconnect it rather than looking for a manual “refresh” button. Connect the service again with OAuth, and set the new credential as the default. A manual one-click OAuth refresh in the app is a known limitation and should not be relied on.

To rotate a key-based credential, connect the service again with the new key, mark it as the default, and delete the old one. See managing credentials.

What it costs

How a connected service is billed depends on which method you used to connect it.

Your own key (BYOK)

Usage is billed directly by the service provider, with no ModuleX markup. It is not metered in ModuleX credits.

ModuleX-managed key

Tool calls made through a ModuleX-managed key are metered in credits. When your plan’s allowance runs out, calls are subject to the usage gate — see usage gating & limits.

Troubleshooting

I do not see the connect or Add credential controls

Connecting integrations requires the owner or admin role for the organization. Switch to the correct organization in the header, or ask an owner or admin to connect the service. See roles & permissions.

The OAuth window returned an error

Start the connection again from the catalog. The sign-in step is time-limited, so if you waited too long on the consent screen, the attempt expires and you simply retry. If the service reports that access was denied, approve the requested permissions when prompted.

My API key was rejected

Double-check you copied the full key from the service, with no extra spaces, and that it has the permissions the action needs. ModuleX tests a key before saving, so a rejection here means the service did not accept it.

The tool node does not list my integration

Confirm the credential was saved in the same organization you are building the workflow in, and that the integration shows as connected. If you connected more than one account, check which credential is set as the default.

My run was blocked with a limit or credit error

Tools that use a ModuleX-managed key consume credits. If your plan’s allowance is exhausted, the run is stopped by the usage gate. See usage gating & limits and errors & troubleshooting.

Next steps

Integrations overview

What integrations are, how the catalog is organized, and how to browse 175 services.

Tool node

The full reference for calling one integration action from a workflow.

Managing credentials

List, set defaults for, test, and delete the credentials your organization has connected.

Integration authentication

The connect methods a service can offer and how each secret is stored and resolved.

Billing & credits

Data & limits

Guides

Power using

Connect an integration

Before you start

An account in an organization

The owner or admin role

An account on the service

How connecting works

Three ways to connect

OAuth (recommended)

Your own key (BYOK)

ModuleX-managed key

Connect a service with OAuth

Connect with your own key instead

Use the tool in a workflow

Connect a service from code

Keep a connection working

What it costs

Your own key (BYOK)

ModuleX-managed key

Troubleshooting

Next steps

Integrations overview

Tool node

Managing credentials

Integration authentication

​Before you start

An account in an organization

The owner or admin role

An account on the service

​How connecting works

​Three ways to connect

OAuth (recommended)

Your own key (BYOK)

ModuleX-managed key

​Connect a service with OAuth

​Connect with your own key instead

​Use the tool in a workflow

​Connect a service from code

​Keep a connection working

​What it costs

Your own key (BYOK)

ModuleX-managed key

​Troubleshooting

​Next steps

Integrations overview

Tool node

Managing credentials

Integration authentication

Before you start

How connecting works

Three ways to connect

Connect a service with OAuth

Connect with your own key instead

Use the tool in a workflow

Connect a service from code

Keep a connection working

What it costs

Troubleshooting

Next steps