Choosing an Authentication Method
Read this guide to learn more about the different types of authorization available for your monday app, as well as the best use-cases for each.
Determining which authentication method to use in your app can be difficult and confusing.
When designing your app, you should consider what data it needs to access. Any data that comes from a user’s monday.com account must be accessed via the monday GraphQL API.
Additionally, if your app accesses data from other platforms, you should consider their authentication protocols as well.
How do you authenticate with the monday API?
The monday API uses token-based authentication. To successfully authenticate with our GraphQL API, every request should include an API token in the request’s “Authorization” header.
Generally speaking, there are four ways your app can get an access token to use:
- Seamless Authentication using monday SDK
- Seamless Authentication using shortTermToken
- Using an OAuth Access Token
- Using a user’s global API token
Method 1: Seamless Authentication
We offer two mechanisms for seamless authentication, which eliminate most of the overhead of user and token management in your app. We recommend using Seamless Authentication if your app only needs to make API calls when a user is interacting with it.
Using Seamless Authentication has the following advantages:
- Your app does not need to store and manage API keys
- You can host client-side apps fully on monday servers
- Your users do not need to take additional steps to authorize your app or supply an API key
Seamless authentication in a view app using the monday SDK
If your app is a view (board view, item view, or widget) you can use the
monday.API() method in our SDK to make API calls on behalf of the logged in user. Our apps framework will handle the rest.
Seamless authentication only works when your app is open in a client. It currently supports making queries and mutations to our API but does not support file uploads.
Tip: If you need to make API calls in the background or upload files, we recommend implementing OAuth.
Seamless Authentication in integration recipes using shortLivedToken
You can also use seamless authentication in integration recipes. Every request from the Monday server to your app will be accompanied with a JWT token in the authentication header.
When you decode the JWT token, you will see a
shortLivedToken field. This is an API token that is valid for 1 minute and can be used to authenticate against the monday.com API. To learn more, check out this article: Integration Authorization.
When is seamless authentication not an option for me?
Seamless authentication will work for almost every app use case. However, there are a few exceptions:
- If your app needs to make API calls without user input
- If your integration needs to make API calls for longer than 1 minute after the monday server sends you a request
- If your client-side app needs to make an API call from the backend/server-side.
Method 2: Using OAuth to issue access tokens
Your app can also use OAuth to get authentication tokens. Simply put, OAuth allows your app to ask for user authorization before accessing their account, and will receive an API key once authorized. If your app needs to store a user’s API token or make API calls in the background, OAuth is a good option.
Benefits of OAuth:
- Quick and painless permission-granting for your app users
- Ability to make API calls in the background for an extended period of time and without user input
- Tokens are scoped to your app automatically and you don’t have to worry about deleting the token when your app is uninstalled
To implement OAuth in a board view or a dashboard widget, you will need to establish the logic in your backend to retrieve an access token (that will give you access to a user’s data) from our token endpoint: https://auth.monday.com/oauth2/token.
To implement OAuth in your integration recipe, you will need to set up an authorization URL on your own server that will initiate the process of obtaining an access token.
For more detailed information on this process, we recommend reading up on our OAuth & Permissions article.
Method 3: Using a user’s global API token
If you’re looking to build a quick app that prioritizes easy development over security (for example, something only your team uses), you can store a user’s API token. Each user has a global API token that can be accessed by going to their Avatar > Developers tab, and your app can use this to authenticate with the API.
We don’t recommend this method for most apps, for the following reasons:
- The API token is not scoped (ie, it can do everything)
- The user only has one token at a time -- if they are using the token with another tools and needs to regenerate it, your app will need to get the new token
- The API token is only specific to a particular user, so if you want your app to be usable for many users, you will need all of those API tokens
Note: Any apps that utilize this authentication method will not pass our approval process for our apps marketplace. Learn more about submission guidelines for our apps marketplace here.