Only show these results:
public-beta

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.

The API version selector is shown with the dropdown open.

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:

  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. 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:

  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:
    • Email and Contacts scopes
    • Calendar scope
  3. This creates two separate Nylas accounts that each have their 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.

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:

  1. Google and Exchange accounts
  2. Office 365 accounts with OAuth
    • Uses the Email and Contacts scopes
    • No event webhooks
  3. 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

Billing

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