monday.com integration
Sign monday.com users into your product, keep their monday.com tokens working, and see every install and automation run.
If your product ships a monday.com app, BuildBase handles everything between monday.com and your users. It knows who installed the app and which of your users they are, and it has a working monday.com token when your server needs one. Your app keeps doing what only it can do: the automation itself.
Before you start
You need a monday.com app in monday.com's Developer Center, and a BuildBase plan that includes the monday.com integration. Connect it in the BuildBase console under Apps > monday.com.
What it is for
Say your app adds an automation to monday.com: "When an item is created, create a document in YourApp and link it on the item." To run it, your server needs two things monday.com does not hand over. It needs to know which of your users the monday.com account belongs to, and it needs a monday.com token to write the link back.
| You want to | BuildBase does |
|---|---|
| Sign a monday.com user in to your product | Runs monday.com's OAuth sign-in, finds the user in your app by their monday.com email (or creates one when sign-up is open), and sends your app a signed token naming both |
| Call the monday.com API for that user, at any time | Stores the token encrypted, refreshes it before it expires, and hands your server a working one from the Token URL |
| Know who installed, upgraded or uninstalled the app | Records every lifecycle event, forwards it to your server, and lets you resend one your server missed |
| Email the people who installed it | Process events adds every installer to your audience |
| See what your automations did, and for whom | Lists every action your server reports, for the whole app and on each user's page |
How it works
Install. monday.com tells BuildBase about every install, uninstall and subscription change. BuildBase records the event and creates the installer as a user of your app, as long as sign-up is open and your plan has room. Then it forwards the event to your server.
Sign-in. The first time someone adds one of your automations, monday.com sends them to BuildBase. BuildBase asks monday.com for their permission, stores the token it gets, and matches the person to a user in your app by their monday.com email. It then sends them to your app with a signed token. The next time, they skip the permission screen.
Run. monday.com calls your server directly to run an automation. When your server needs to call monday.com for that user, it asks BuildBase for a token. Afterwards it reports the outcome, which shows on the Activity tab.
Sign-out. When someone removes their saved sign-in in monday.com, BuildBase revokes its tokens at monday.com and deletes its own copy.
Uninstall. The uninstall event removes the account's stored tokens.
What stays in your app
- The automation itself. monday.com calls your server's automation URLs directly, with a JWT signed with your app's Signing Secret. That JWT carries a
shortLivedTokenthat works for five minutes, which is enough for work done during the run. - What a signed-in user means to you. The signed token names the BuildBase user and the monday.com account. Linking that to your own records is up to your app.
How the keys are used
| Key | Signs or checks |
|---|---|
| Client secret | monday.com's lifecycle events, the token sent to your app, and your server's requests to BuildBase |
| Signing secret | monday.com's sign-in hand-off, and its requests to the credentials field |
| Client ID | Who your app is, in the OAuth sign-in and in monday.com's lifecycle events |
Tokens are encrypted at rest. monday.com access tokens last a day and the refresh token never leaves BuildBase, because monday.com replaces it on every use.
Next steps
- Set up your monday.com app - where each key is, and where each URL goes
- Connect your app server - the signed token, the Token URL, events and action reports