OAuth 2.0 is a protocol that lets your app request authorization to read or modify data in a user's monday account. 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.

You can set up OAuth for your app in two distinct phases: configuring your app and going through the standard OAuth flow.

Configure your scopes and redirect URLs

To start, you must first configure your app's scopes and redirect URLs. If you don't have an app, follow these steps to create an app in the monday UI and locate your client_id and client_secret.

Once your app has been created, set the scopes and redirect URLs in the OAuth tab in the Developer Center.

Permission scopes

OAuth scopes define what your app can and cannot do. Each endpoint in the monday API requires a certain permission scope that can be found in our API reference.

When you ask a monday user to grant access to your app, you have to specify which of the following supported scopes you're requesting access to:

Redirect URLs

After a monday user approves or denies your app’s authorization request, they will be redirected back to your app's specified redirect_uri. You can use multiple URLs if you want to route users to different pages based on their context.

The OAuth flow

Once you've created and configured your monday app, you're ready to go through the standard OAuth flow. A successful OAuth authorization between your app, the user, and the monday OAuth server occurs in the following order:

1. Make an authorization request and redirect the user to the monday OAuth URL with the client ID: https://auth.monday.com/oauth2/authorize
2. The user sees the permission scopes your app is requesting and approves the request.
3. The user is redirected to a defined URL (redirect URL) with a temporary authorization code in the query params after approval.
4. Your app's backend sends a POST to the token request endpoint with this code. The token endpoint will respond with an access token. The access token gives your app access to the monday API on behalf of the user and will be valid until the user uninstalls your app.

Authorization request

The first step in the OAuth flow is making an authorization request and redirecting a user to the monday OAuth page. The OAuth request URL is: https://auth.monday.com/oauth2/authorize.

Example: GET https://auth.monday.com/oauth2/authorize?client_id=1111

Redirect

After the user grants permission to your app in step 2, they will be redirected to your app using the provided redirect_uri as part of step 3. We will add the authorization code, scope, and state to query parameters:

Token request and response

Once you have obtained an authorization code from the authorization endpoint, you can exchange it for an access token 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.

Request structure

The HTTP verb in your request should be POST, and the token URL is https://auth.monday.com/oauth2/token.

Response structure

On success, the response contains the status 200 OK in the header and the following JSON data in the body:

The JSON body of the response will look like the following:

{
   "access_token": "NgeFeX...FEmEka", 
   "token_type": "Bearer",
   "scope": "boards:write boards:read"
}

OAuth flow for users with multiple accounts

Some monday.com users will be part of multiple accounts, so your app may want to specify which account to authorize the user for. In the standard OAuth flow, the user can select the monday.com account where they'd like to authorize using a dropdown menu.

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 using the account slug: constructing the URL or adding a query parameter.

Constructing the URL

This method involves constructing the URL with the slug/subdomain of the account, or the first part of the URL that comes before .monday.com. Users can still change the account using the dropdown, but the slug you specify will be the default. You can easily access an account's slug by querying the account through monday API.

Let's say we queried the account and the slug is awesomeapp. The OAuth flow URL would look like this:

https://awesomeapp.monday.com/oauth2/authorize?client_id=<CLIENT_ID>&redirect_uri=<YOUR_URL>

Adding a query parameter

Instead of constructing the URL, you can add the subdomain=<ACCOUNT_SLUG> query parameter to the URL to create the link using their account slug. Unlike the previous option, users can't change the account using the dropdown since they are forced to use this specific slug.

Using the example above, the URL would look like this:
https://auth.monday.com/oauth2/authorize?client_id=<CLIENT_ID>&redirect_uri=<YOUR_URL>&subdomain=awesomeapp

Error codes

On an error of any kind, the user will be redirected back to the specified redirect_uri. The possible errors you can get are:

📘

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! 😎