Version:
Only show these results:

Create an Azure auth app

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

Changes to Microsoft auth apps in v3

⚠️ If you're upgrading from Nylas v2 to v3, you must create a new Azure auth app. Your v2 Azure app is not compatible with v3, and v3 apps aren't compatible with Nylas v2. When you migrate your end users to the new auth app, they must re-authenticate their accounts and approve the app. Some end users might also need to get admin approval for it to access their accounts.

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

  • Nylas now supports Account in any organizational directory and personal Microsoft accounts. This allows end users to authenticate using their personal (non-business) accounts.
  • EWS- and EAS-related scopes have been removed, and you must now use Graph scopes.
  • 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.

Calculating scopes

If you're authenticating with Microsoft in Nylas v3, you must use Microsoft Graph scopes (also sometimes called "feature permissions" or "API permissions").

If you're starting a new project, Nylas recommends you make a list of the APIs your project uses, then compile a list of the scopes you need using the v3 scopes documentation. If you're migrating from v2, you might be able to translate your old Exchange/EAS scopes into Microsoft Graph scopes. It's a security best practice to only request scopes that you actually use, however for development purposes, you might choose broader scopes than your production app needs.

You'll add these scopes to your Azure auth app's Entra ID system (previously "Azure ID") in the Enable required APIs step below. For more information, see Microsoft's official Configure Azure AD Graph permissions for an app registration guide.

As you work with Nylas, you might need to update your scopes for specific APIs (for example, you might want Write permissions for your end users' email messages). You can find API-specific scope information throughout this documentation:

Create an Azure OAuth application

💡 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. Click App registrations.
  3. Click New registration.
  4. Give your application a name. This name will be visible to your end users.
  5. 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.
  6. Set the Redirect URI platform to Web and enter your project's redirect URI.
    • If you're using Hosted auth, enter https://api.us.nylas.com/v3/connect/callback (U.S. region) or https://api.eu.nylas.com/v3/connect/callback. (E.U. region)
    • If you're using Custom auth, enter your project's callback URI.
  7. Review Microsoft's Platform Policies, then click Register.
    Microsoft Azure Portal displaying the "Register an application" page.

Enable required APIs

✨ You can now enable the APIs that Nylas requires without modifying the manifest in your Azure app. If you prefer to use the manifest, you can follow the instructions in Enable required APIs with manifest.

After you create your OAuth app, you must add the required permissions to your Azure app. This enables the APIs that your application requires.

  1. In the Microsoft Azure Portal, go to Home > App registrations and select your application.
  2. From the left navigation menu, select API permissions.
  3. Click Add a permission.
  4. Select Microsoft Graph from the list of APIs.
  5. Select Delegated permissions.
    • If you plan to use bulk authentication, select Application permissions and add all Microsoft Graph scopes that your project needs access to. For more information, see Use a Microsoft bulk authentication grant.
  6. Enable the following permissions:
    • 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.
    • At least one feature permission: These permissions, also known as "scopes", allow Nylas to read data from the provider.
  7. Click Add permissions.

If your Azure app was previously registered with a manifest, you might get the following error message:

One or more of the following permission(s) are currently not supported: EWS.AccessAsUser.All. Please remove these permission(s) and retry your request.

If this happens, you can either enable the required APIs with a manifest or create a new Azure auth app.

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

(Optional) Enable required APIs with manifest

If you use the application manifest, you can update an Azure app directly by editing its JSON. For more information, see Microsoft's official AD Manifest documentation.

To enable the required APIs using the application manifest, follow these steps:

  1. In the Microsoft Azure Portal, select Manifest from the left navigation menu.
  2. Find requiredResourceAccess in the code panel.
  3. Update requiredResourceAccess to include the following permissions:
  4. Click Save.

Create OAuth credentials

Next, you need to create your OAuth credentials:

  1. In the Microsoft Azure Portal, navigate to Home > App registrations and select your application.

  2. From the left navigation menu, select Certificates & secrets.

  3. Click New client secret.

  4. Enter a Description of the client secret, and set an expiration date of 730 days (24 months).
    Microsoft Azure Portal displaying the Add a Client Secret dialog.

  5. Click Add.

  6. Copy the value from the Azure Client secrets page and save it to your secrets manager.

    ⚠️ Be sure to save the client secret value somewhere secure. Azure shows the value only once, and if you navigate away from this page you cannot retrieve the key value. For best practices, see Storing secrets securely.

    Microsoft Azure Portal displaying the "Client secrets" page.

  7. Navigate to the App registrations page and copy the Application (client) ID for your app.
    The Microsoft Azure Portal showing the "App registrations" page. One application is listed, along with its client ID.

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

Add a Microsoft connector to Nylas

Finally, you need to add a Microsoft connector to your Nylas application. You can create a connector either using the Nylas v3 Dashboard, or by making an API request.

Create connector using the Nylas Dashboard

  1. Log in to the v3 Dashboard, and navigate to the Nylas application you're creating the connector for.
  2. Select Connectors from the left navigation.
  3. In the Microsoft tile, click the add symbol (+).
  4. Under Microsoft credentials, enter your Azure client ID and Azure client secret.
    • Set the Azure tenant to common to allow authentication for accounts that are outside of your organization.
  5. Under Authenticate scopes, select the required scopes.
  6. Click Save.

Create connector using the Nylas API

To add a connector using the Nylas API, make a Create Connector request. The following code sample demonstrates how to use your Azure app's client ID and secret to add the Microsoft connector to Nylas.

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": "<AZURE_CLIENT_ID>",
      "client_secret": "<AZURE_CLIENT_SECRET>",
      "tenant": "common"
    },
    "scope": [
      "offline_access",
      "openid",
      "profile",
      "User.Read",
      "Calendars.Read",
      "Calendars.ReadWrite",
      "Mail.ReadWrite",
      "Mail.Send"
    ]
  }'

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

Update your Azure client secret

Microsoft's Azure client secrets expire after two years. When a secret expires, it invalidates the associated Nylas grants. For best practices on updating your Azure client secret, see How to renew Microsoft Azure client secret for your Nylas application.