Graph API for Office 365

Cronofy has developed a new integration for connecting Office 365 calendars using Microsoft’s Graph API. This will replace Exchange Web Services (EWS) as our preferred integration mechanism in the future.

Microsoft’s Graph API provides two key benefits:

Cronofy can request more granular permissions than EWS, leading to less friction in administrator consent
Cronofy can use Teams conferencing as an integrated conferencing provider, with no additional end-user authorization required, in the same way Google Meet works for Google Calendars currently

At the moment Cronofy supports Microsoft’s Graph API for tenants hosted on Office 365. We cannot yet support on-premise Exchange or hybrid tenants.

Microsoft’s Graph support for hybrid tenants is still in Preview, and does not include the full set of API endpoints that Cronofy requires. As and when Microsoft update this, Cronofy will work to support hybrid scenarios through its Graph integration.

Enabling Graph for your application #

This is an entirely new mechanism for synchronizing Office 365-based accounts. Given the scope of the change we felt it wise to offer it initially as an opt-in feature to allow developers to test it with their own applications.

We’ve been testing internally and with end-users of our own published applications, and are confident in it, but it’s not been hardened by real world usage at large scales yet.

In the future, we will make this default connection mechanism for all Office 365 accounts and remove the need to opt-in.

To enable the feature, visit the (new) Features section for your application in the Cronofy developer dashboard.

Connecting calendars via Individual Connect #

After the feature is enabled, Individual Connect authorization attempts for Office 365 will use Graph instead of EWS. The only user-facing change is that the Microsoft authorization flow will present a different (less permissive) set of scopes.

If you have existing profiles connected, you can go through the authorization flow again for them, and they’ll be switched over. If you disable the feature, the same steps will switch a profile back to synchronizing via EWS.

Connecting calendars via Enterprise Connect #

Enterprise Connect with Graph is simpler to configure for calendar administrators than Exchange Web Services. No service account on the Exchange side is needed. Instead, it works similarly to the Google Workspace integration - the administrator only needs to approve the connection using their admin account. Please see our Graph API documentation for calendar administrators here.

A Cronofy Service Account is still created for your application to interact with the organization, and you will still receive Cronofy Service Account credentials in the same way.

Once the Graph API feature is enabled, the Cronofy authorization flow for service accounts will create a Graph connection by default. The option to create an EWS-based connection still exists as a secondary option during the flow.

A Graph Service Account will return a new provider_name value of ms_graph_calendars when calling the UserInfo endpoint. Requesting delegated access to users’ or resources’ calendars through a Graph service account will switch over any existing profiles that are currently synchronizing via Exchange Web Services to use the Graph connection instead.

Connecting specific organizations #

You may wish to connect specific organizations via Graph Enterprise Connect without opting-in your entire application to the feature.

To do this, you can pass an additional query string value of provider_name=ms_graph_calendars to the authorization URL, which will force a Graph connection, even if the opt-in feature is not enabled.

Parity with EWS #

Given we expect to make this the preference globally in time, we’ve focused on parity with our existing EWS implementation to avoid any breaking/unexpected changes for developers.

Calendar profiles will still appear as having provider_name of exchange on a UserInfo endpoint response.

The clearest indication over the Cronofy API that you’re connected to a profile via Graph is that (assuming Teams is available on your Office 365 subscription) calendars’ integrated_conferencing_available flag will be true, and events made in Graph calendars requesting conferencing.profile_id: "integrated" will get Teams conference calls added.

There are currently some known differences compared to EWS:

Event geolocation coordinates are returned with a slightly different degree of precision. This makes no real world difference, but you may receive push notifications that events have changed as a result.
Graph gives us richer information about calendars. Built-in national holidays calendars can now be detected as read-only, where they couldn’t before.