OAuth and Permissions

## 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. 
**Create an app:** To create an app,  go to your profile and click ‘monday apps  - monday apps.
**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!
**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. 
## 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`
<table>
  <tr>
    <th>Parameter</th>
    <th>Description</th>
    <th>Default Value</th>
    <th>Required/Optional</th>
  </tr>
  <tr>
    <td>client_id</td>
    <td>The identifier of your app, from the Basic Information page</td>
    <td></td>
    <td>Required</td>
  </tr>
  <tr>
    <td>redirect_uri</td>
    <td>URL to redirect back on approval/denial. Must match one of the redirect URL you've added to your app.</td>
    <td>If you've only configured one redirect_uri, it will be used. Otherwise, this parameter is required.</td>
    <td>Required if more than one redirect_uri is configured.</td>
  </tr>
  <tr>
    <td>scope</td>
    <td>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.</td>
    <td>The full scope list you've configured to your app</td>
    <td>Optional</td>
  </tr>
  <tr>
    <td>state</td>
    <td>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.</td>
    <td></td>
    <td>Optional</td>
  </tr>
  <tr>
    <td>app_version_id</td>
    <td>The ID number of the app's version.</td>
    <td></td>
    <td>Optional</td>
  </tr>
</table>
NOTE
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:
<table>
  <tr>
    <th>Parameter</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>code</td>
    <td>The generated authorization code, valid for 10 minutes.</td>
  </tr>
  <tr>
    <td>state</td>
    <td>The state parameter you supplied in the previous step.</td>
  </tr>
</table> 
### 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:
`https://<SLUG>.monday.com/oauth2/authorize?client_id=<CLIENT_ID>&redirect_uri=<YOUR_URL>`
TIP
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.
#### 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.
NOTE
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:
`https://auth.monday.com/oauth2/authorize?client_id=<CLIENT_ID>&redirect_uri=<YOUR_URL>&subdomain=<SLUG>`
## 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: 
<table>
  <tr>
    <th>Error Code</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>400</td>
    <td>invalid_request</td>
  </tr>
  <tr>
    <td>403</td>
    <td>unauthorized_client</td>
  </tr>
  <tr>
    <td>403</td>
    <td>access_denied</td>
  </tr>
  <tr>
    <td>403</td>
    <td>invalid_scope</td>
  </tr>
  <tr>
    <td>500</td>
    <td>server_error</td>
  </tr>
  <tr>
    <td>500</td>
    <td>temporary_unavailable</td>
  </tr>
</table>
## 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)
<table>
  <tr>
    <th>Parameter</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>client_id</td>
    <td>The identifier of your app, from the Basic Information section</td>
  </tr>
  <tr>
    <td>client_secret</td>
    <td>The app's secret, from the Basic Information section</td>
  </tr>
  <tr>
    <td>redirect_uri</td>
    <td>This parameter is used for validation only (there is no actual redirection). The value must match the value supplied in the Authorization Request step.</td>
  </tr>
  <tr>
    <td>code</td>
    <td>The authorization code from the previous step.</td>
  </tr>
</table>
### 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:
<table>
  <tr>
    <th>Key</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>access_token</td>
    <td>An access token that can be used to make calls to the monday.com API.</td>
  </tr>
  <tr>
    <td>token_type</td>
    <td>Bearer -- all monday OAuth tokens are bearer token.</td>
  </tr>
  <tr>
    <td>scope</td>
    <td>A comma-separated list of scopes that have been granted for this access token.</td>
  </tr>
</table>
This is what the JSON body of the response will look like: 
﻿
## 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:
﻿[Quickstart Guide: Views & Widgets](🔗﻿) 
﻿[Quickstart Guide: Integration Recipes](🔗﻿) 
﻿[API documentation](🔗﻿)﻿
Join our developer community!
We've created a <a href="https://community.monday.com/c/developers/8" target="_blank"> community</a> 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! 😎