Microsoft Graph for Events
This feature is in public beta. It might contain bugs, and might change before it is generally available.
Nylas offers Microsoft Graph permissions for events only. We recommend using Graph for events if you currently don’t use Nylas for Calendar or events. If you currently use calendar, please see our recommendations for existing calendar customers.
Enable Graph in Your Dashboard
Click on App Settings on the left and select API Version 2.3 or higher from the dropdown.
If you're currently on a version between 1.0 - 2.0, changing the version is a breaking change. Review our transition guide to see how to upgrade to 2.1.

New Customers
No changes are needed. You’ll be able to select the Graph scopes when creating your Azure app.
Existing Email and Contact Only Customers
If you want to use Graph, you’ll have to delete and then re-authenticate the account with new scopes.
Deleting the account removes any associated data. Once the account authenticates, Nylas will re-sync the account data. The accounts won't have any connection to each other.
Delete the extra account
If you decide not to delete the account and instead re-authenticate the same account with new Graph scopes, we'll bill you for 2 accounts.
Existing Calendar Accounts
If you don't want to enable Microsoft Graph, no changes are required.
If you want to start using Microsoft Graph, follow the instructions below:
- You’ll need to authenticate the account as a new account with the calendar-only scope. Nylas will create a new account with a separate
account_id
. - The account will re-sync calendar data based on your webhook and sync policy.
- Once the new account is authenticated, delete the old account. You will be billed for two accounts if you don't delete the old one.
Azure Account Scopes
If you want to use Graph, add the new scopes to your Azure app:
Calendars.Read.Shared
Calendars.ReadWrite.Shared
Your users will need to re-authenticate with these new scopes.
Supported Authentication
We only support OAuth for Graph scopes.
Hosted Authentication
For hosted authentication, you'll need to create an Azure app and have the Client ID and Client Secret linked to Nylas.
Native authentication
For Native authentication (renamed to "Custom authentication" in v3), you must authenticate using the refresh token, Azure Client ID, and Client Secret. When you make the authentication request, pass in graph
as the provider.
curl -X POST https://api.nylas.com/connect/authorize -d '{
"client_id": "<NYLAS_CLIENT_ID>",
"name": "Nyla the Cheetah",
"email_address": "[email protected]",
"provider": "graph",
"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 the was originally used to get the refresh token
},
"scopes": "calendar"
}'
Shared Microsoft Calendars
This currently only applies to Office 365 users and is for API version 2.3 or higher. We recommend creating a new Nylas application for using shared Microsoft calendars. The new Nylas application requires a separate webhook setup as well as the Azure Client ID and Client Secret.
Process for Native Authentication
Follow the steps below to authenticate an account or migrate an existing user:
- Request the
Calendars.ReadWrite.Shared
scope for all accounts that need to use shared calendars. - Pass the same refresh tokens twice during the Send Authorization step for Nylas native authentication for the following:
Email
andContacts
scopesCalendar
scope
- This creates two separate Nylas accounts that each have their own unique ID values and access tokens.
- In your system, link the Nylas accounts to the user. Use the correct tokens for requests to calendar, email, or contacts.
Things to Keep In Mind
Ignore webhooks from accounts authenticated using the email and contacts scopes as we still sync calendars on these accounts. To work around this, you can create a separate production application with the email and contacts scopes authenticated. Once that's done, deactivate event webhook triggers.
With this solution, your organization has three production Nylas applications for the following setups:
- Google and Exchange accounts
- Office 365 accounts with OAuth
- Uses the
Email
andContacts
scopes - No event webhooks
- Uses the
- Office 365 accounts with Microsoft OAuth
- Only uses the
Calendar
scope - Event webhooks with the Graph accounts application on API version 2.3 or higher
- Only uses the
Billing
Contact Nylas to resolve any issues with duplicate charges for a single user.