App Connections

An app connection links your Gravity Rail workspace to an external service — a CRM (HubSpot, Salesforce), a project management tool (Monday.com), an EHR (eClinicalWorks, Epic, Cerner, Athena, Healthie), a chat platform (Slack, Discord), or a custom tool server (MCP). Once connected, you can sync members and records, trigger automations from external events, and give your AI agents access to data and actions in those systems.

App Connections is the integration hub for your workspace. Every external service you wire up — whether it's a one-click OAuth integration like Gmail or a complex multi-board sync like Monday.com — appears here. The page consolidates platform integrations, MCP servers, Discord bots, Slack apps, FHIR connections, and CRM sync connections into a single browse-and-manage experience.

Browsing Available Integrations

Go to App Connections to open the integration hub. The page has two tabs:

• Active — every connection currently configured in your workspace, grouped by type.
• Directory — every integration you can add, with an Install button for each.

Filtering and Searching the Directory

The Directory tab supports both search and category filters so you can quickly find an integration:

• Search — type a name (e.g., "Monday", "Linear", "FHIR") in the search box.
• Category filters — narrow by Messaging, Google, Healthcare, Project Management, Vehicle & IoT, or Tools.
• View toggle — switch between Grid (card view, default) and List (compact rows).

Each directory tile shows the integration name, a short description, an icon, and a badge if you already have one or more connections of that type configured.

Connecting an Integration

Most integrations use OAuth — you'll be redirected to the external service to authorize Gravity Rail, then sent back to your workspace once the grant is complete.

General OAuth Flow

1. On the Directory tab, find the integration you want
2. Click Install
3. Follow the setup wizard:
   • For OAuth integrations: click Connect to launch the provider's authorization page, sign in with the account you want to use, and approve the requested scopes
   • For API key integrations (e.g., Healthie): paste the API key and submit
   • For URL-based integrations (e.g., custom MCP servers): paste the server URL and configure auth as prompted
4. After the provider redirects you back, the new connection appears on the Active tab

Use a service account where possible. OAuth grants are tied to the user who authorized them. If that user leaves your organization or revokes Gravity Rail's access, the connection breaks. For production CRM, calendar, and EHR integrations, authorize with a dedicated service account rather than a personal one.

Integration-Specific Setup

Some integrations have additional setup steps documented in their own guides:

• Monday.com — see Monday.com Setup for app creation and OAuth, then Monday.com Sync for board mappings and sync rules
• HubSpot — see HubSpot Sync for sync rules, CEL expressions, and field filters
• Salesforce — see Salesforce for CRM sync configuration
• Healthie — see Healthie for appointment and patient sync
• Slack — see Slack Bots for app creation and bot setup
• Discord — see Discord Bots for bot setup
• Confluence — see Confluence Sync for space mapping and sync configuration

Viewing Connected Apps and Their Status

The Active tab is where you check on connections that are already wired up. Connections are grouped by type:

• Platform Integrations — OAuth-based platform apps (Gmail, Google Calendar, Confluence, etc.)
• CRM Connections — HubSpot, Salesforce, Monday.com
• Healthcare Connections — FHIR (eClinicalWorks, Epic, Cerner, Athena), Healthie
• MCP Servers — Linear, Sentry, Notion, DeepWiki, PayPal, NetSuite, custom URLs
• Discord Bots — configured Discord bot integrations
• Slack Apps — configured Slack app integrations

Each row shows:

• Name — the connection's display name (you can rename it in settings)
• Status badge — Connected, Disabled, Reauthorize Required, or Error
• Action menu — View, Edit, Settings, Sync now, Disable, or Delete

Click a row to expand it and see additional details: the OAuth account in use, available tools, last sync time, and any error messages from the provider.

Configuring an Active Connection

After a connection is installed, click Settings (or open the connection's detail page) to configure it.

Renaming a Connection

Several integrations support multiple connections of the same type (for example, two HubSpot portals or several Monday.com workspaces). Give each one a descriptive name so AI agents and automations pick the right one:

1. Open the connection's settings
2. Edit the Name field
3. Click Save

Configuring Sync

Sync-capable connections (HubSpot, Salesforce, Monday.com, FHIR/eClinicalWorks) support bidirectional data sync — keeping members and records in step between Gravity Rail and the external system. Sync is configured per entity type (member, record, calendar event, file).

For each entity type you want to sync:

1. Open the connection's Sync tab
2. Add or edit the entity sync config:
   • Outbound — push Gravity Rail data to the external system
   • Inbound — pull external data into Gravity Rail
   • Match Strategy — how to find existing records (typically by email, external ID, or phone)
   • Conflict Policy — what to do when both sides have changed (skip, prefer-source, prefer-target)
   • Filter — an optional CEL expression that limits which entities sync (e.g., source.email != '' && source.age >= 18)
   • Rules — named groups of field mappings, each with its own CEL transforms
3. Click Save
4. Click Sync now to run an initial pass, or wait for the schedule to pick it up

For a complete walkthrough of sync rules, CEL expressions, and field transforms, see HubSpot Sync — the same concepts apply to all sync-capable connectors.

Trust and Scope Settings

Some integrations expose tools that AI agents can call (for example, "create a HubSpot note", "upsert a Monday.com item", or "look up a FHIR patient"). To control which agents can use them:

1. Open the connection's Settings tab
2. Review the Tools section — each tool lists the action it performs
3. Toggle individual tools on or off
4. For agent permissions, attach the connection's tools to a workflow's task or to an agent's abilities — see Custom Toolkits for the full ability-attachment flow

Principle of least privilege. Only grant the scopes and tools you actually need. If a workflow only needs to read Salesforce contacts, don't grant write access. Re-authorize the connection with a narrower scope set if your provider supports it.

Disconnecting and Revoking Access

There are two ways to remove a connection:

Disable

Disable keeps the configuration in place but stops the connection from being used:

1. On the Active tab, click the action menu next to the connection
2. Choose Disable
3. Confirm

A disabled connection can be re-enabled at any time without re-running OAuth. Use Disable when you want to pause a sync or temporarily stop AI agents from using a tool.

Delete

Delete removes the connection entirely, including stored OAuth tokens and configuration:

1. On the Active tab, click the action menu next to the connection
2. Choose Delete
3. Confirm — this is destructive

Sync rules, board mappings, and any custom configuration are deleted. To reconnect, install the integration again from the Directory tab and re-run setup.

Also revoke from the provider side. Deleting a connection in Gravity Rail removes our copy of the OAuth token, but most providers also keep their own record of the grant. To fully revoke access, sign in to the provider (e.g., HubSpot, Salesforce, Google) and remove the Gravity Rail integration from their connected-apps list.

Currently Supported Integrations

This list grows over time. The Directory tab in your workspace always reflects the current set of available integrations, including any that are gated behind feature flags for your plan or organization.

Tips

• Authorize with a service account — OAuth grants are tied to a user. Personal accounts cause connections to break when people leave or revoke access.
• Name connections descriptively — "HubSpot — Production Portal" beats "HubSpot 2" when an agent has to pick between two.
• Test sync on a small filter first — Add an outbound_filter like source.labels.exists(l, l == 'sync-test') to limit your first sync to a handful of test members before opening the floodgates.
• Check the Active tab after every redeploy — Reauthorize Required badges show up here when a token expires or a provider rotates secrets.
• Disable, don't delete, when troubleshooting — Disabling preserves config so you can re-enable and inspect the same setup once the issue is resolved.

Troubleshooting

"Reauthorize Required" badge

The provider's access token has expired, been revoked, or had its scopes changed. Open the connection and click Reauthorize to re-run the OAuth flow with the same account. If the original authorizing user no longer has access, set up a new connection with a service account instead.

"Insufficient scopes" or "permission denied" errors

The OAuth grant didn't include the scopes the integration needs. Common causes:

• The user authorizing did not approve all requested scopes — re-run authorization and approve everything
• The provider account lacks admin privileges for the requested resources (e.g., a Salesforce user without API access)
• The integration was authorized before a new feature was added — disconnect and reconnect to pick up the new scope set

Sync isn't picking up changes

• Verify the entity has both Outbound (or Inbound) Enabled in the connection's Sync tab
• Check the filter CEL expression — if it returns false for your entity, sync skips it
• Open the connection's detail page and look at Last Sync — repeated failures show their error messages there
• For inbound sync, verify the provider's webhook or change-feed is reaching Gravity Rail — see Webhooks for diagnosis

"Tool not found" or AI agent says it can't reach the integration

• Confirm the connection is on the Active tab and not Disabled
• Verify the tool is enabled in the connection's Settings → Tools section
• Check that the workflow task or agent ability has the integration's tools attached — see Custom Toolkits

Duplicate records appearing after sync

The Match Strategy isn't finding existing records, so sync creates new ones. Common causes:

• Match by email, but external records have empty or differently-cased emails
• Match by external ID, but the IDs aren't populated yet on the Gravity Rail side
• A new entity type was added without a match strategy

Switch to a different match key (e.g., email + phone fallback), populate the missing field, or run a one-time reconciliation from the connection's detail page.

Can't disable or delete a connection

If a connection is referenced by an active workflow ability or sync rule, the UI prevents deletion. Detach the connection from those references first, then retry. Workspace admins (the apps:admin scope) are the only roles allowed to delete connections — if the option is missing, ask a workspace admin to perform the action.

Related

• HubSpot Sync — Detailed sync rule configuration with CEL expressions
• Monday.com Setup — Create a Monday.com app and connect it
• Monday.com Sync — Board mappings, sync rules, and automations
• Salesforce — Connect to Salesforce CRM
• Healthie — Sync appointments and patients with Healthie EHR
• Slack Bots — Deploy AI bots in Slack
• Discord Bots — Deploy AI bots in Discord
• Custom Toolkits — Attach connection tools to AI agents
• Webhooks — Receive events from external systems
• Apps & API Keys — OAuth grants and API keys for the Gravity Rail API