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:
- A Monday.com account with admin access to the boards you want to sync.
- Workspace admin permissions in Gravity Rail.
Step 1: Create a Monday.com App
- Open your Monday.com account and click your profile picture in the top right corner.
- Select Developers. The Developer Center opens in a new tab.

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


- 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.

- 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.

For more details on the Developer Center, see Monday's documentation.
Step 2: Install Monday.com and copy the callback URL
- In your Gravity Rail workspace, open Connections > Manage in the sidebar (the App Connections page).
- 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.
- 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
- Back in the Monday.com Developer Center, go to Build > OAuth & Permissions.
- Select the Redirect URLs tab and paste the OAuth Callback URL from Gravity Rail.

-
Select the Scopes tab and enable the following scopes:
boards:readboards:writeme:readupdates:writewebhooks:readwebhooks:write

- Click Save changes.
Step 4: Enter credentials and connect
- 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.

-
Click Connect Monday.com (step 3).
-
You'll be redirected to Monday.com to authorize the app. Review the permissions and click Authorize.

- You'll be redirected back to Gravity Rail.
Once connected, you'll see a green "Connected" badge on the Active tab of Connections > Manage.

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:
| Tab | Purpose |
|---|---|
| Overview | Sync 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 |
| Members | View and manage links between Gravity Rail members and Monday items |
| Data Types | View Data Type records linked to Monday items |
| Settings | What to sync: board mappings and sync rules |
| Sync | Sync Now, dry runs, and sync activity, progress and errors |
| Data | Read-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 |
| Setup | Account and authorization details, your app credentials (Update credentials), the OAuth callback URL, and requested scopes |
What Permissions Does Gravity Rail Request?
| Scope | What it allows |
|---|---|
me:read | Read your user profile information |
boards:read | Read board data and items |
boards:write | Create and update items |
account:read | Read account info |
webhooks:write | Subscribe 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.
Related
- 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)