monday.com connector setup

Operator·4 minutes to read

This page is the setup half — creating the OAuth app monday.com needs in its own Developer Center and getting its client id and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to monday.com.

This connector uses monday.com's OAuth 2.1 flow with PKCE. Most older tutorials describe the legacy flow, whose access tokens monday.com stopped accepting on 2026-10-01 — follow this page, not them.

1. Create the OAuth app in the monday.com Developer Center

  1. In monday.com, open the Developer Center and create a new app — this is your own app, not Botseon's. monday.com's own reference for the flow is Migrating to the new OAuth flow.

  2. On the app's OAuth tab, add the redirect URL from docs/connectors/README.md — with the quickstart's default BOTSEON_PUBLIC_URL, that is:

    http://127.0.0.1:3000/api/oauth/monday/callback

  3. On the same tab, select the four scopes in section 2. monday.com only grants scopes that are configured here.

  4. Open Basic Information and copy the Client ID and Client secret.

You do not need monday.com's approval to let other accounts install the app: share its install link directly. The price is a banner during consent saying monday.com has not vetted the app; only a public marketplace listing, which goes through monday.com's review, removes it.

2. Scopes

Request the narrowest set that covers the tools this connector exposes (F-PLUG-1: minimum scopes per capability, read and write requested separately):

Read:

  • boards:read — read your boards and their items.
  • updates:read — read the updates on items.

Write, on top of the read set:

  • boards:write — create items and change their column values.
  • updates:write — post an update on an item. An update notifies the item's subscribers, so this tool's approval card names the item and the update's text is disclosed on the card.

3. Enter the app

One command, with the client secret on standard input — there is no flag that takes it and no environment variable that holds it (see docs/connectors/README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug monday \
  --client-id <the client ID from step 1> \
  --auth-url https://auth.monday.com/oauth2/authorize \
  --token-url https://auth.monday.com/oauth_ms/oauth/token \
  --configured-by <your user id>

The token URL is the OAuth 2.1 one, https://auth.monday.com/oauth_ms/oauth/token — not the legacy https://auth.monday.com/oauth2/token.

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug monday says whether an app is configured and under which client id; nothing prints the secret back.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.

4. What this connector does and does not do

  • monday.list_boards — the boards this account can see, one page at a time.
  • monday.get_board — one board, its columns and its groups.
  • monday.list_items — one page of up to 100 of a board's items, and a marker that fetches the next page.
  • monday.get_item — one item, its column values and its latest updates.
  • monday.create_item — creates an item on a board. Tagged write; the approval card names the board.
  • monday.update_item — changes an item's column values. Tagged write; the approval card names the item.
  • monday.comment — posts an update on an item. Tagged write and external_send, because the update notifies the item's subscribers; the approval card names the item and the update's text is disclosed on the card.

Every request pins monday.com's API version 2026-07 with the API-Version header, so a new quarterly version never changes what this connector reads.

monday.com caps API calls at 1,000 a day on its Free, Standard and Basic plans, and every query also spends from a per-minute complexity budget. When either runs out a member may notice a pause before a bot's next monday.com call.

Access tokens are short-lived and refreshed automatically. The refresh token stays valid as long as it is used at least once every three months; after that, the member authorises again.

monday.com's EU data region is for Enterprise accounts, and its documentation does not say it changes the API address, so this connector calls https://api.monday.com/v2 regardless.

This connector's catalogue row ships available: false: it stays disabled until the live smoke runs at turn-on.

Last verified against build 331481c.