Microsoft Authentication
When you authenticate accounts with Microsoft, you need to decide if you want to use OAuth or Basic Authentication. Administrators can configure their app to use either protocol.
Prerequisites
We recommend reading our guides on Hosted and Native Authentication:
Native Authentication
Microsoft has two types of Exchange authentication:
Administrators can choose which authentication protocol to use.
For security reasons, we recommend using OAuth or Modern Authentication. Additionally, Microsoft will be deprecating Basic Authentication support for all Exchange Online accounts as of October 1, 2022.
Basic Authentication
Exchange or Basic Authentication is a former authentication protocol for Microsoft. Basic Authentication uses a username and password flow. The steps to set up Basic Authentication are:
- Create a branded page where users will enter their login credentials.
- Make a request to /connect/authorize with the user-provided credentials in the settings and required scopes.
Autodiscovery
Nylas will attempt to automatically discover the exchange host. You can turn this feature off by adding exchange_server_host
to the settings. See Exchange Auto-discovery for more information.
Exchange Accounts Example
curl -X POST https://api.nylas.com/connect/authorize -d '{
"client_id": "nylas_client_id",
"name": "Nyla the Cheetah",
"email_address": "[email protected]",
"provider": "exchange",
"settings": {
"username": "[email protected]",
"password": "MakeEmailSuckLess",
"exchange_server_host": "exchange.nylas.com"
},
"scopes": "email.read_only,calendar.read_only,contacts.read_only"
}'
- In the response, Nylas will return a one-time use code that you can exchange for an
access_token
. - Now that you have your one-time use code, send a request to /connect/token to get an access token.
Modern or OAuth Authentication
OAuth for Microsoft requires that you do the following:
- Obtain a refresh_token.
- Create an Azure app.
- Follow the steps to go through domain verification.
- Become a Microsoft verified publisher.

To set up Modern or OAuth Authentication, follow the steps below:
- Make sure you've created an Azure App.
- Redirect the user to your OAuth login page.
- Microsoft then sends the authentication code to your application.
- Request the refresh_token from Microsoft. When requesting the refresh token, set
tenant
tocommon
and setscope
tooffline_access https://outlook.office365.com/EAS.AccessAsUser.All https://outlook.office365.com/EWS.AccessAsUser.All openid profile User.Read
- Microsoft then returns the
refresh_token
. - Make a request to /connect/authorize using the
microsoft_client_id
,microsoft_client_secret
(from your Azure application), and themicrosoft_refresh_token
.
Example Microsoft POST Send Authorization Request
curl -X POST https://api.nylas.com/connect/authorize -d '{
"client_id": "nylas_client_id",
"name": "Nyla the Cheetah",
"email_address": "[email protected]",
"provider": "office365",
"settings":{
"microsoft_client_id": "{microsoft_client_id}",
"microsoft_client_secret": "{microsoft_client_secret}",
"microsoft_refresh_token": "{microsoft_refresh_token}",
"redirect_uri": "https://example.com/redirect", # Redirect URI that was originally used to get the refresh token
},
"scopes": "email.read_only,calendar.read_only,contacts.read_only"
}'
- Nylas returns a one-time use authorization code.
- Make a request to /connect/token.
Example POST Exchange the Token Request
curl -X POST "https://api.nylas.com/connect/token" -d '{
"client_id": "{client-id}",
"client_secret": "{client-secret}",
"code": "{nylas_code}"
}'
- Nylas returns an
access_token
for the account. - Follow the steps to go through domain verification.
- Become a Microsoft verified publisher.
Hosted Authentication
Hosted Authentication follows the OAuth 2.0 process. Nylas takes care of the authentication when using Hosted Authentication.
Hosted Authentication for Microsoft requires that you do the following:
- Create an Azure app.
- Follow the steps to go through domain verification.
- Become a Microsoft verified publisher.
Microsoft Hosted Authentication Steps
- Create an Azure App.
- Follow the steps to set up Hosted Authentication.
Nylas will attempt to detect the exchange host. If we're unable to, the user is given the option to enter the exchange host.

Exchange Autodiscovery
Native Authentication
When using Native Authentication, Nylas will attempt to automatically detect the provider. You can turn auto-discovery off for Exchange accounts by specifying the exchange_server_host
in the settings.
Hosted Authentication
When using Hosted Authentication, Nylas attempts to discover the Exchange server and guide the user through authentication. If we're unable to find the server, the user will need to enter the server information.
Deactivate Auto-discovery
You can turn auto-discovery off by specifying the exchange_server_host
in the settings.
Some providers, such as Office 365 Native Authentication, don't allow you to turn off the discovery settings.
Microsoft Exchange ActiveSync
Nylas can sync the majority of Exchange accounts. The provider attribute should be set to exchange.
The exchange_server_host
value is optional. If it's not present, Nylas Cloud will attempt auto-discovery for the server host or endpoint.
Things to Keep in Mind
- When requesting the refresh token from Microsoft make sure you properly set the tenant and scope:
- Set
tenant
tocommon
- Set
scope
tooffline_access https://outlook.office365.com/EAS.AccessAsUser.All https://outlook.office365.com/EWS.AccessAsUser.All openid profile User.Read
- Set
- OAuth is the preferred authentication method for security reasons.
- You can turn off Exchange auto-discovery if you're using Native Authentication.
Scopes
Before authorizing a user, make sure you have the correct Nylas scopes in your request. If you need to change scopes, the user will have to re-authenticate.
Example Apps
We've created several Microsoft Authentication applications so you can see how to implement the process in your app: