Skip to main content

Monday.com Setup

Monday.com is a common system of record for care coordination teams — tracking enrollments, referrals, outreach status, and patient demographics. The Monday.com App Connection lets you sync that data with Gravity Rail so your AI workflows, Data Types, and member profiles stay current without manual updates.

This guide covers creating a Monday.com app and connecting it to Gravity Rail. Once connected, see Monday.com Sync to configure board mappings and sync rules.

How It Works​

The Monday.com connection uses OAuth to link your Monday account to your Gravity Rail workspace. Setup is guided: you install Monday.com in Gravity Rail (which shows you the OAuth callback URL before you need any credentials), create a Monday.com app in your account's Developer Center with that callback URL, enter the app's credentials in Gravity Rail, and authorize the connection. Once authorized, Gravity Rail can read your boards and items, create and update items, and subscribe to board change events via webhooks.

Each Gravity Rail workspace needs its own Monday.com app — even if multiple workspaces connect to the same Monday.com account. This ensures each workspace has its own permissions and callback URL.

Before You Start​

You'll need:

  1. A Monday.com account with admin access to the boards you want to sync.
  2. Workspace admin permissions in Gravity Rail.

Step 1: Create a Monday.com App​

  1. Open your Monday.com account and click your profile picture in the top right corner.
  2. Select Developers. The Developer Center opens in a new tab.

Click your profile picture, then select Developers to open the Developer Center

  1. Click Create your first app (or Create app if you already have apps).

The Developer Center landing page with the Create your first app button

The Developer Center with existing apps and the Create app button

  1. Enter an App name (e.g., "Gravity Rail Sync") and an App slug (e.g., "gravityrail-sync"). The app slug is permanent and cannot be changed later — choose a stable, descriptive identifier. Click Create app.

The Create new app dialog with app name and slug fields

  1. In the left menu, go to General Settings. Under App Credentials, copy the Client ID, Client Secret, and Signing Secret — you'll need these in the next step.

General Settings showing App Credentials with Client ID, Client Secret, and Signing Secret

For more details on the Developer Center, see Monday's documentation.

Step 2: Install Monday.com and copy the callback URL​

  1. In your Gravity Rail workspace, open Connections > Manage in the sidebar (the App Connections page).
  2. Find Monday.com in the list of available connections and click Add, then confirm Add. This creates the connection and opens its page with a Setup in progress badge — you don't need any credentials yet.
  3. Open Setup. Step 1 of the guide shows your OAuth Callback URL and the required OAuth scopes. Copy the callback URL — you'll add it to your Monday.com app next.

Step 3: Configure OAuth in Monday.com​

  1. Back in the Monday.com Developer Center, go to Build > OAuth & Permissions.
  2. Select the Redirect URLs tab and paste the OAuth Callback URL from Gravity Rail.

The OAuth & Permissions page showing the Redirect URLs tab with the callback URL added

  1. Select the Scopes tab and enable the following scopes:

    • boards:read
    • boards:write
    • me:read
    • updates:write
    • webhooks:read
    • webhooks:write

The Scopes tab with the required scopes enabled

  1. Click Save changes.

Step 4: Enter credentials and connect​

  1. Back in Gravity Rail's guided setup, click Enter credentials (step 2) and enter the Client ID, Client Secret, and Signing Secret from your Monday.com app. Click Create.

The Configure Monday.com dialog with fields for Client ID, Client Secret, and Signing Secret

  1. Click Connect Monday.com (step 3).

  2. You'll be redirected to Monday.com to authorize the app. Review the permissions and click Authorize.

The Monday.com authorization screen showing the requested permissions and the Authorize button

  1. You'll be redirected back to Gravity Rail.

Once connected, you'll see a green "Connected" badge on the Active tab of Connections > Manage.

The App Connections page showing Monday.com with a green Connected badge

Set up from the command line (optional)​

The same steps are available through the Gravity Rail CLI -- handy for scripted setup or when a workspace agent performs the configuration. Run gr monday install --help for the full sequence.

# 1. Create the connection. The response includes the OAuth "callbackUrl".
gr monday install -w <workspace-uuid> --allow-write

# 2. Register that callbackUrl + scopes on your Monday.com app, then save credentials.
gr monday configure -w <workspace-uuid> --allow-write \
-d '{"clientId":"...","clientSecret":"...","signingSecret":"..."}'

# 3. Authorize. Open the returned "authorizeUrl" in a browser to grant access.
gr monday authorize -w <workspace-uuid>

# Check progress at any time (shows configured / connected + the callback URL).
gr monday status -w <workspace-uuid>

The Monday.com Connection Page​

After connecting, the page has seven tabs.

The header keeps the connection status visible on every tab. Open its three-dot menu for Reconnect, Test connection, or Disconnect when available. An error or expired grant shows Reconnect directly in the header. Disconnect asks for confirmation. Last synced, when present, opens the successful run on Sync.

Use each tab for its own task:

TabPurpose
OverviewSync success rate and Linked, Unlinked, Unlinkable and Errored Member counts. Unlinkable counts Members that lack the identity fields the match strategy reads. Under Match by phone the count is conservative: a Member with an email counts as reachable, so 0 does not prove every Member is reachable. Match by custom field and an API-configured strategy show 0. When records fail to sync, Sync issues below the counts lists each cause, how many records it affects and what to do; select the Errored count to go there
MembersView and manage links between Gravity Rail members and Monday items
Data TypesView Data Type records linked to Monday items
SettingsWhat to sync: board mappings and sync rules
SyncSync Now, dry runs, and sync activity, progress and errors
DataRead-only: which Data Types the connection uses, how many of their records you can see, and where each mapped field lives in Gravity Rail. See Seeing Where Monday Keeps Its Data
SetupAccount and authorization details, your app credentials (Update credentials), the OAuth callback URL, and requested scopes

What Permissions Does Gravity Rail Request?​

ScopeWhat it allows
me:readRead your user profile information
boards:readRead board data and items
boards:writeCreate and update items
account:readRead account info
webhooks:writeSubscribe to board change events (for inbound sync)

Monday.com access tokens do not expire. Once connected, the integration stays active until you disconnect it.

Troubleshooting​

"Connect Monday.com" Button Does Nothing​

Make sure you've entered the Client ID and Client Secret in the configuration dialog first. Open Setup and choose Update credentials to change them.

OAuth Redirect Fails​

Check that the OAuth Callback URL in your Monday.com app's Build > OAuth & Permissions > Redirect URLs exactly matches the OAuth callback URL shown on the Gravity Rail Setup tab. Even a trailing slash difference will cause the redirect to fail.

"Awaiting OAuth" Status Won't Change​

After clicking Authorize in Monday.com, you should be redirected back to Gravity Rail and the status should change to "Connected." If it stays on "Awaiting OAuth," verify that all five scopes are enabled in your Monday.com app and that the redirect URL is correct.

Connection Shows Error State​

If the connection still shows Connected, choose Test connection from the header's three-dot menu. For an error or expired grant, click Reconnect in the header and authorize again. To disconnect first, choose Disconnect in the menu and confirm, then open Setup and repeat the authorization in Step 4. Your saved app credentials remain available.

After Disconnect, past runs remain read-only on Sync (also reached through Last synced, when present), and sync controls stay unavailable until you reconnect.

Tips​

  • Copy credentials carefully. Use the copy buttons in the Monday.com Developer Center rather than selecting text manually. A missing character in the Client Secret will cause a cryptic OAuth error.
  • Test the connection immediately. After completing Step 4, choose Test connection from the header's three-dot menu before moving on to sync configuration.
  • Bookmark your Developer Center app. You'll return to it if you need to update scopes or check the signing secret.

Next Steps​

Now that your Monday.com account is connected, see Monday.com Sync to configure board mappings, sync rules, and automations.

  • Monday.com Sync — Configure board mappings, sync rules, and automations
  • App Connections — Overview of all available connections
  • HubSpot Sync — Sync rules, CEL expressions, and filters (same concepts apply to Monday.com)