Permissions

This walkthrough of how Cronofy considers permissions on end users’ calendar events is important to review when working with the Cronofy API.

The core principle is consideration of people’s data privacy and security and that the principle of least privilege should be applied. For this reason, we believe that the existing models provided by calendar services do not serve the needs of application developers and their users.

The Cronofy API treats events that your application creates (Partner Events) differently to events that the user creates in their calendar directly (External Events).

The APIs provided by the calendar services from Google, Microsoft and others provide a fairly simple permissions system. Some are are essentially binary, giving you access to everything or nothing. Others are more nuanced in that they can provide free-busy-only access but this precludes the option to write events to a user’s calendar when a booking is made.

By treating these two types of events separately, the Cronofy API can enable a rich set of use cases without giving your application unnecessary permissions and thus making it necessary to deal with data or functionality that your application does not need to.

Creating Events #

If the user grants your application permission to create events via the authorization flow, your application will be able to not only create events but have full control over updating and/or deleting the events it creates.

Your application doesn’t need permission to read events and thus can, if your use case requires it, create events in a user’s calendar at arbitrary times.

In the Request Authorization flow you request the write_only scope to achieve this. It’s important to recognize that this write_only refers to Partner Events and does not grant permissions to External Events. See Editing Events below for more information.

Free-busy #

If you need to deliver on scheduling use cases then access to free-busy information for External Events is important. Often this is all of the information your application needs in order to make a scheduling decision.

Some calendar services do provide free-busy only permissions onto calendars but this prevents applications from writing events to the calendar. Instead you will need full read-write access to both query free-busy as well as to write events for bookings.

This is where Cronofy’s approach to Partner and External Events really adds value.

You are able to combine free-busy only access to External Events with full write permissions to Partner Events to power your booking flow without your application needing to process the private information in a user’s calendar.

In the Request Authorization flow you request the free_busy_write scope to achieve this.

Reading A User’s Events #

In many use cases it is advantageous to be able to read the contents of External Events. Perhaps you want to provide a user with a visualization of a day or provide them more context to decide whether or not they can reschedule a previously arranged meeting.

The read_ scopes provide your application with the ability to request this permission as part of the Request Authorization flow.

Reading Another User’s Events #

Cronofy only provides access to events in calendars that the authorized user has an ownership, or equivalent, permission on. This is again a consideration of people’s data privacy and security.

If Jane has shared her calendar with Marcel, and Marcel connects his calendar to a third party application, why should Jane’s data be implicitly shared with that application. As a default, if Jane wants to take advantage of the application her data should only be shared explicitly.

There are situations, especially in business applications, where this sharing is desired so we provide authorization approaches that ensure this is achieveable explicitly rather than implicitly. See the Authorization & Authentication section for more information.

Editing Events #

Editing Partner Events is the default. Your application has created them and thus has full permissions on those events.

Editing External Events, i.e. those that the user has created, is the highest level operation and one that we believe should be explicitly granted rather than be the default. The vast majority of use cases that require access to calendars do not need to be able to edit or delete the existing contents of users’ calendars.

Giving applications the ability to wipe out someone’s schedule is dangerous. It shouldn’t be granted lightly.

However, in order to support those use cases where it is required we provide an Extended Permissions flow. Slightly different approaches are taken depending on the authorization approach.

Individual Connect #

Adding this authorization as an additional step in the authorization process allows the application to request access to one, some or all calendars within a user’s calendar service Profile.

Once the access_token has been obtained for the Account, your application can then request the Extended Permissions and redirect the user to the returned url. Once the user has accepted this elevation, your application will be able to edit/delete External Events in the granted calendars.

Enterprise Connect #

An alternative scope is requested from the admin authorizing the domain to allow elevated permissions to be granted for the users in that domain. service_account/accounts/unrestricted_access instead of service_account/accounts/manage with a corresponding scope for Resources.

Then the Permissions are requested, but the redirect doesn’t need to be followed; they are automatically granted to the accounts.

Creating Calendars #

Your application can obtain permission to create calendars in a user’s calendar service Profile by requesting the create_calendar scope when authorizing.

Your application will be automatically granted the elevated permissions required to edit all events, Partner or External, that are created in that calendar.

Summary #

As you can see from this walkthrough, we’ve thought very carefully about how permissions are handled at Cronofy. Your application should have the minimum access required to deliver the functionality needed. This protects both you and your users and builds the trust required to unlock more use cases.