Only show these results:
Public Beta

Microsoft Graph for Events

Nylas now 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

Go to App Settings and select API Version 2.3 from the dropdown.

If you are on versions 1.0 - 2.0 changing the version is a breaking change. Review our transition guide to see how to upgrade to 2.1.

The API version selector is shown with the dropdown open.

Version 2.2 and 2.3

The only change between version 2.2 and version 2.3 is the addition of the Graph permissions.

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 then reauthenticate the account with new scopes.

Deleting the account means the previous data is gone. Once the account is authenticated, Nylas will re-sync the account data. The accounts will not be connected in any way.

Delete the extra account

If you decide not to delete the account and instead reauthenticate the same account with new Graph scopes. You’ll be charged for 2 accounts. The accounts are not connected in any way.

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.

  1. 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.
  2. The account will re-sync calendar data based on your webhook and sync policy.
  3. Delete the previous account, once the new account is authenticated. Otherwise, you will be billed for two accounts.

Delete the extra account

If you decide not to delete the account and instead reauthenticate the same account with new Graph scopes; You’ll be charged for 2 accounts. The accounts are not connected in any way.

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 reauthenticate with the new scopes.

Supported Authentication

We will only support OAuth for Graph scopes.

Hosted Authentication

You will need to create an Azure app and have the client ID and secret linked to Nylas.

Native Authentication

You’ll need to authenticate using the refresh token, Azure client ID, and client secret. When making 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. We recommend creating a new Nylas application for using shared Microsoft calendars. This setting is for API version 2.3. The new Nylas application requires separate webhook setup as well as Azure client ID and client secret credentials.

Process for Native Authentication

Follow the steps below for authenticating an account or migrating an existing user.

  1. Request the Calendars.ReadWrite.Shared scope for all accounts that need to use shared calendars.
  2. Pass the same refresh tokens twice during the Send Authorization step for Nylas native authentication for the following.
    1. Email and Contacts scopes
    2. Calendar scope
  3. This creates two separate Nylas accounts. Each account has its own unique ID values and access tokens.
  4. In your system, link the Nylas accounts to the user. Use the correct tokens for requests to calendar, email, or contacts.

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 email and contacts scopes authenticated. From there, 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 Microsoft OAuth
    • Uses Email and Contacts scopes
    • No event webhooks
  • Office 365 accounts with Microsoft OAuth
    • Only uses Calendar scope
    • Event webhooks with the Graph accounts application on API version 2.3

Billing

Contact Nylas to resolve issues with double charges for a single user.