OAuth and Permissions

Authenticating monday apps with OAuth2 and defining permission scopes.

Getting Started with OAuth2

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.

The OAuth Flow

Here are the steps for a successful OAuth authorization between your app, the user, and the monday.com OAuth server.

  1. Redirect the user to the monday OAuth URL with the client ID - https://auth.monday.com/oauth2/authorize
  2. The user will see an approval page that lists the permission scopes your app is requesting. The user approves the request.
  3. After approval, the user is redirected to a URL that you define (redirect URL), with a temporary authorization code in the query params.
  4. 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.

Registering a monday app

Before users can authorize your app with their monday.com account, first you need to register it in our web UI.

  1. Create an app: Follow these steps to create an app on monday.

  2. Find your client_id & client_secret: After registration, your app will be given a client_id and client_secret. These credentials are unique and belong to your app only. The client_id is 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!

  3. Configure your scopes: OAuth scopes define what your apps can and cannot do. You can learn more about permission scopes in the next section.

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

Set Up Permission Scopes

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

Set Up Redirect URIs

Once a monday user approves/denies your app request for access, he will be redirected back to your app, to a specified configured redirect_uri.

Authorization Request

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.

Request Structure and Examples

  • The OAuth request URL is: https://auth.monday.com/oauth2/authorize
  • Example: GET https://auth.monday.com/oauth2/authorize?client_id=1111
Parameter Description Default Value Required/Optional
client_id The identifier of your app, from the Basic Information page Required
redirect_uri 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.
scope 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 Optional
state 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. Optional
app_version_id The ID number of the app's version. Optional



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.

Redirect Structure & Examples

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:

Parameter Description
code The generated authorization code, valid for 10 minutes.
state The state parameter you supplied in the previous step.

OAuth Flow for Users with Multiple Accounts

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:

First Method: Account Slug

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

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:

query { 
  boards {
    owner {
      account {

There is another way to make sure the user stays on the same account as well.

Second Method: Query Parameter

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:

Error Codes

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:

Error Code Description
400 invalid_request
403 unauthorized_client
403 access_denied
403 invalid_scope
500 server_error
500 temporary_unavailable

Token Request

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.

Request Structure and Examples

  • The token URL is https://auth.monday.com/oauth2/token
  • The HTTP verb should be POST
  • Parameters: clientId, clientSecret, authCode (as x-form-urlencoded)
Parameter Description
client_id The identifier of your app, from the Basic Information section
client_secret The app's secret, from the Basic Information section
redirect_uri This parameter is used for validation only (there is no actual redirection). The value must match the value supplied in the Authorization Request step.
code The authorization code from the previous step.

Response Structure & Examples

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

Key Description
access_token An access token that can be used to make calls to the monday.com API.
token_type Bearer -- all monday OAuth tokens are bearer token.
scope 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:

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

Token Expiration and Refresh Tokens

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.

Congratulations Builder!

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