Only show these results:

Create an Azure auth app for Nylas API v3

This page explains how to create and configure a Microsoft OAuth application to use with Nylas API v3.

Changes to Microsoft auth apps in v3

The steps to create and configure a Microsoft OAuth app for the Nylas API v3 should be pretty familiar, but some things have changed:

  • Supported account types have been updated to be Account in any organizational directory and personal Microsoft accounts. This allows for OAuth of personal accounts.
  • EWS- and EAS-related scopes have been removed.
  • Added a cURL request example to connect your Azure app to Nylas.
  • The Authorized redirect URIs have been updated:
    • For U.S. Hosted authentication use https://api.us.nylas.com/v3/connect/callback.
    • For E.U. Hosted authentication use https://api.eu.nylas.com/v3/connect/callback.

Create an OAuth application to use with v3

💡 If you don't already have one, create your free Microsoft Azure account. You'll use this account to create the Microsoft developer application that you use to authenticate end users using OAuth with Nylas.

Follow these steps to create an Azure app for authenticating your users to Microsoft 365:

  1. Log in to the Microsoft Azure Portal.
  2. Search for App registration and navigate to the resulting page.
  3. Give your application a name. This name will be visible to your end users.
  4. Set the audience for the app to Accounts in any organizational directory and personal Microsoft accounts. This allows end users to log in using any Microsoft account.
    • If you're building an internal app (used only by members of your organization), you can restrict access to internal accounts only by setting the audience to Accounts in this organizational directory only.
  5. Set the Redirect URI platform to Web and enter your redirect URI.
    • If you're using Hosted auth, enter https://api.us.nylas.com/v3/connect/callback.
    • If you're using Custom auth, enter your app's callback URI.
  6. Click Register.

Microsoft Azure Portal displaying the Register an Application page.

Enable required APIs

After you create your OAuth app, you must add the permissions that the app needs to function to your Azure app's manifest. This enables the APIs that your application requires.

The table below describes the permissions that are available for Azure apps.

Permission Required? Description
offline_access ☑️ Read and update end user data, even when the user is offline.
openid ☑️ Sign end users in to the app.
profile ☑️ View end users' basic profiles.
User.Read ☑️ Allow end users to sign in to the app, and allow the app to read their profiles.
Calendars.Read Read end users' calendars.
Calendars.ReadWrite Allow read and write access to end users' calendars.
Mail.Send Send email messages as an end user.
Mail.ReadWrite Allow read and write access to end users' email accounts.

For more information, see Microsoft's official permissions reference.

Create OAuth credentials

Next, you need to create your OAuth credentials:

  1. From the Azure Portal, go to Home > App registrations and select the app you want to configure.
  2. On the left navigation menu, select Certificates & secrets > New client secret.
  3. Enter a description of the client secret, and set an expiration date of 24 months.
    Microsoft Azure Portal displaying the Add a Client Secret dialog.
  4. Click Add.
  5. Copy the value from the Azure Client secrets page and save it to your secrets manager. Note that Azure shows the value only once, and if you navigate away from this page you cannot retrieve the key value.
    Microsoft Azure Portal displaying the Client Secrets page.
  6. Navigate to the App registrations page and copy the Application (client) ID for your app.
    Microsoft Azure Portal displaying the App Registrations page. An application named Nylas and its client ID are displayed.

📝 Note: Azure credentials include an expiration date. When these credentials expire you must refresh or regenerate them.

Add Microsoft connector to Nylas

Finally, you need to add the Microsoft connector to your Nylas environment.

The following code sample demonstrates how to use your Azure app's client ID and secret to add the Microsoft connector to Nylas.

💡 Tip: Use tenant: "common" to allow authentication for accounts that are outside of your organization.

curl -X POST https://api.us.nylas.com/v3/connectors \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "microsoft example",
"provider": "microsoft",
"settings":
{
"client_id": "<microsoft_client_id>",
"client_secret": "<microsoft_client_secret>",
"tenant": "common"
},
"scope": [
"offline_access",
"openid",
"profile",
"User.Read",
"Calendars.Read",
"Calendars.ReadWrite",
"Mail.ReadWrite",
"Mail.Send"
]
}'