# 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[​](#browsing-available-integrations "Direct link to 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[​](#filtering-and-searching-the-directory "Direct link to 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[​](#connecting-an-integration "Direct link to 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[​](#general-oauth-flow "Direct link to 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[​](#integration-specific-setup "Direct link to Integration-Specific Setup")

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

* **Monday.com** — see **[Monday.com Setup](https://docs.gravityrail.com/user-guide/app-connections/monday-setup.md)** for app creation and OAuth, then **[Monday.com Sync](https://docs.gravityrail.com/user-guide/app-connections/monday-sync.md)** for board mappings and sync rules
* **HubSpot** — see **[HubSpot Sync](https://docs.gravityrail.com/user-guide/app-connections/hubspot-sync.md)** for sync rules, CEL expressions, and field filters
* **Salesforce** — see **[Salesforce](https://docs.gravityrail.com/user-guide/channels/salesforce.md)** for CRM sync configuration
* **Healthie** — see **[Healthie](https://docs.gravityrail.com/user-guide/channels/healthie.md)** for appointment and patient sync
* **Slack** — see **[Slack Bots](https://docs.gravityrail.com/user-guide/channels/slack.md)** for app creation and bot setup
* **Discord** — see **[Discord Bots](https://docs.gravityrail.com/user-guide/channels/discord-bots.md)** for bot setup
* **Confluence** — see **[Confluence Sync](https://docs.gravityrail.com/user-guide/app-connections/confluence-sync.md)** for space mapping and sync configuration

## Viewing Connected Apps and Their Status[​](#viewing-connected-apps-and-their-status "Direct link to 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[​](#configuring-an-active-connection "Direct link to Configuring an Active Connection")

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

### Renaming a Connection[​](#renaming-a-connection "Direct link to 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[​](#configuring-sync "Direct link to 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](https://docs.gravityrail.com/user-guide/app-connections/hubspot-sync.md)** — the same concepts apply to all sync-capable connectors.

### Trust and Scope Settings[​](#trust-and-scope-settings "Direct link to 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](https://docs.gravityrail.com/user-guide/abilities/custom-toolkits.md)** 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[​](#disconnecting-and-revoking-access "Direct link to Disconnecting and Revoking Access")

There are two ways to remove a connection:

### Disable[​](#disable "Direct link to 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 "Direct link to 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[​](#currently-supported-integrations "Direct link to Currently Supported Integrations")

| Integration               | Category           | Capabilities                                                                        |
| ------------------------- | ------------------ | ----------------------------------------------------------------------------------- |
| **Gmail**                 | Productivity       | Read and send email from a connected Google account                                 |
| **Google Calendar**       | Productivity       | Sync events with a Google Calendar                                                  |
| **HubSpot**               | CRM                | Bidirectional member sync, notes, tasks, AI tools                                   |
| **Salesforce**            | CRM                | Bidirectional member/record sync, notes, tasks, AI tools                            |
| **Monday.com**            | Project Management | Bidirectional member/item sync, multi-board mappings, automations, webhook triggers |
| **eClinicalWorks** (FHIR) | Healthcare         | Patient data, encounters, observations, care plan items                             |
| **Epic** (FHIR)           | Healthcare         | Patient data via FHIR R4                                                            |
| **Cerner** (FHIR)         | Healthcare         | Patient data via FHIR R4                                                            |
| **Athena** (FHIR)         | Healthcare         | Patient data via FHIR R4                                                            |
| **Generic FHIR**          | Healthcare         | Connect to any FHIR R4-compatible EHR                                               |
| **Healthie**              | Healthcare         | Appointment sync, patient reconciliation                                            |
| **Slack**                 | Communication      | Bot messaging, channel monitoring, slash commands                                   |
| **Discord**               | Communication      | Bot commands, DMs, gateway events                                                   |
| **Confluence**            | Knowledge          | Sync Confluence pages and spaces to your knowledge base                             |
| **MCP Servers**           | Developer          | Linear, Sentry, Notion, DeepWiki, PayPal, NetSuite, or any custom MCP URL           |

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[​](#tips "Direct link to 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[​](#troubleshooting "Direct link to Troubleshooting")

### "Reauthorize Required" badge[​](#reauthorize-required-badge "Direct link to \"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[​](#insufficient-scopes-or-permission-denied-errors "Direct link to \"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[​](#sync-isnt-picking-up-changes "Direct link to 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](https://docs.gravityrail.com/user-guide/developer/webhooks.md)** for diagnosis

### "Tool not found" or AI agent says it can't reach the integration[​](#tool-not-found-or-ai-agent-says-it-cant-reach-the-integration "Direct link to \"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](https://docs.gravityrail.com/user-guide/abilities/custom-toolkits.md)**

### Duplicate records appearing after sync[​](#duplicate-records-appearing-after-sync "Direct link to 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[​](#cant-disable-or-delete-a-connection "Direct link to 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[​](#related "Direct link to Related")

* **[HubSpot Sync](https://docs.gravityrail.com/user-guide/app-connections/hubspot-sync.md)** — Detailed sync rule configuration with CEL expressions
* **[Monday.com Setup](https://docs.gravityrail.com/user-guide/app-connections/monday-setup.md)** — Create a Monday.com app and connect it
* **[Monday.com Sync](https://docs.gravityrail.com/user-guide/app-connections/monday-sync.md)** — Board mappings, sync rules, and automations
* **[Salesforce](https://docs.gravityrail.com/user-guide/channels/salesforce.md)** — Connect to Salesforce CRM
* **[Healthie](https://docs.gravityrail.com/user-guide/channels/healthie.md)** — Sync appointments and patients with Healthie EHR
* **[Slack Bots](https://docs.gravityrail.com/user-guide/channels/slack.md)** — Deploy AI bots in Slack
* **[Discord Bots](https://docs.gravityrail.com/user-guide/channels/discord-bots.md)** — Deploy AI bots in Discord
* **[Custom Toolkits](https://docs.gravityrail.com/user-guide/abilities/custom-toolkits.md)** — Attach connection tools to AI agents
* **[Webhooks](https://docs.gravityrail.com/user-guide/developer/webhooks.md)** — Receive events from external systems
* **[Apps & API Keys](https://docs.gravityrail.com/user-guide/developer/apps.md)** — OAuth grants and API keys for the Gravity Rail API