OAuth 2.0 is a protocol that lets your app request authorization to read or modify data in a user's monday account. Basically, at the end of the OAuth process, your app gets an access token that belongs to the user, and grants access to specified permission scopes.
Here are the steps for a successful OAuth authorization between your app, the user, and the monday.com OAuth server.
- Redirect the user to the monday OAuth URL with the client ID -
- The user will see an approval page that lists the permission scopes your app is requesting. The user approves the request.
- After approval, the user is redirected to a URL that you define (redirect URL), with a temporary authorization code in the query params.
- Your app's backend must send a POST to the token request endpoint with this code. The token endpoint will respond with an access token.
The access token will give your application access to the monday.com API on behalf of the user. This token will be valid until the user uninstalls your app.
Before users can authorize your app with their monday.com account, first you need to register it in our web UI.
Create an app: Follow these steps to create an app on monday.
client_secret: After registration, your app will be given a
client_secret. These credentials are unique and belong to your app only. The
client_idis your app’s unique identifier and will be published publicly. The client_secret is a private string that your application will use in the OAuth flow -- keep it safe!
Configure your scopes: OAuth scopes define what your apps can and cannot do. You can learn more about permission scopes in the next section.
Set up redirect URIs: After a monday.com user approves or denies your app’s authorization request, they will be redirected to a page in your app. This is specified in the Redirect URI section. Using multiple URIs is helpful if you want to route users to different pages based on their context.
Each endpoint in the monday API requires a certain permission scope (can be found in the API docs). When you’re asking a monday user to grant access to your app, you’ll have to specify a list of scopes you’re requesting access to.
The scopes we support are:
me:read - Read your basic personal details
boards:read - Read boards data
boards:write - Modify boards data
workspaces:read - Read user's workspaces data
workspaces:write - Modify user's workspaces data
users:read - Access data about your account's users
users:write - Modify your account's users data
account:read - Access information about your account
notifications:write - Send notifications to users
updates:read - Read updates data
updates:write - Modify updates data
assets:read - Read information of assets that the user has access to
tags:read - Read tags data
teams:read - Read teams data
webhooks:write - Create new webhooks
docs:read - Access workdocs data
docs:write - Create new workdocs
Once a monday user approves/denies your app request for access, he will be redirected back to your app, to a specified configured
The first step in the OAuth flow is making an authorization request. You’ll direct a monday user to the monday.com OAuth page. After the user approves your app, they’ll be redirected back to your app along with an authorization code that will be used to generate an access token in the next step.
- The OAuth request URL is:
|The identifier of your app, from the Basic Information page
|URL to redirect back on approval/denial. Must match one of the redirect URL you've added to your app.
|If you've only configured one redirect_uri, it will be used. Otherwise, this parameter is required.
|Required if more than one redirect_uri is configured.
|A space-separated list of OAuth scopes, indicating the permissions your app is requesting. All requested scopes must match the list you configure in your app.
|The full scope list you've configured to your app
|An arbitrary value that will be passed back to your app on approval or denial. Use a unique state parameter to avoid forgery attacks and check the value at every step of the OAuth flow.
|The ID number of the app's version.
You can now add the app_version_id parameter and the collaborators of the app will be able to go through the OAuth flow for the asked app version.
This works for the collaborators of the app in versions which are either live or drafts.
This will not work for deprecated versions and users which are not collaborators of the app.
After the user grants permission to your app he’ll be redirected back to your app using the
redirect_uri you’ve provided. We will add the authorization code, scope and state to query parameters:
|The generated authorization code, valid for 10 minutes.
|The state parameter you supplied in the previous step.
Sometimes, a monday.com user will be part of multiple monday.com accounts. In this situation, your app may want to specify a specific account to authorize the user for.
In the usual OAuth flow, the user can select the monday.com account where they'd like to authorize using a dropdown menu in the top-right:
If you want to ensure the user authorizes a specific account, you can change the Authorization URL based on their account URL.
There are two methods to do this:
This method revolves around constructing the URL with the slug/subdomain of the account, or the first part of the URL that comes before
.monday.com. For example, if my account URL is awesomeapp.monday.com, the slug would be
Here's how an example of how the OAuth Flow URL would look like:
Using this option, your users can still change the account using the dropdown. The slug you specify will be the default.
You can use the
account field to get an account's slug, via the monday API. Here is an example query:
There is another way to make sure the user stays on the same account as well.
You can add the
subdomain=<ACCOUNT_SLUG> query parameter to the URL, and the link will be created using their account's slug.
This method forces the user to use this slug and they won't be able to change it in the account selection dropdown, presented earlier.
Here's an example of how this would look:
On an error of any kind, the user will be redirected back to the specified
redirect_uri, along with the following parameters as query parameters:
The possible errors you can get are:
Once you have obtained an authorization code from the authorization endpoint, you can exchange it for an access token. The access token can then be used to make calls to monday’s API. The authorization code is only valid for 10 minutes, after which you will have to make another request to get another code.
- The token URL is
- The HTTP verb should be POST
- Parameters: clientId, clientSecret, authCode (as x-form-urlencoded)
|The identifier of your app, from the Basic Information section
|The app's secret, from the Basic Information section
|This parameter is used for validation only (there is no actual redirection). The value must match the value supplied in the Authorization Request step.
|The authorization code from the previous step.
On success, the response has the status 200 OK in the response header, and the following JSON data in the response body:
|An access token that can be used to make calls to the monday.com API.
|Bearer -- all monday OAuth tokens are bearer token.
|A comma-separated list of scopes that have been granted for this access token.
This is what the JSON body of the response will look like:
"scope": "boards:write boards:read"
Access tokens do not expire and will be valid until the user uninstalls your app. Our OAuth flow does not support refresh tokens at the moment.
Continue your monday app development journey with the following resources:
Join our developer community!
We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎
Updated 2 months ago