Getting Started

OAuth & 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

The following is an overview of the steps that go into a successful OAuth authorization between your app, the user, and the monday.com OAuth server.

Your app will first direct the user to the monday.com OAuth page and supply the app’s Client ID. This is where the user will see the permissions your app is requesting and be prompted to authorize it. If the user approves your request, your app will receive a temporary authorization code.

Once your app receives the authorization code, it can make a request to the token request endpoint to exchange this code for an access token that will give your application access to the monday.com API. 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: To create an app, go to your profile and click ‘monday apps - monday apps.
  1. 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!

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

  3. 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 (for example, if they’re on mobile).

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

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

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

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:

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

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
invalid_request
unauthorized_client
access_denied
invalid_scope
server_error
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

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. It is valid for 30 days.
token_type Bearer -- all monday OAuth tokens are bearer token.
scope A space-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.