Calendar Integration Security & Authorization Flow
Admin avatar
Written by Admin
Updated over a week ago


The following document provides the details of how a calendar integration works for coaches. This document is helpful for security conscious teams and individuals to understand the details of how a connected calendar is initiated, connected, and managed.

We have partnered with Nylas to provide best in class calendar services for coaches on the platform. Nylas is a 3rd party service that integrates with calendar systems such as Gmail and Microsoft. Nylas is SOC 2 Type II and ISO-27001 certified. You can read more about their certifications by visiting their page on security.

How It Works

There are 3 major workflows for the calendar integration. All 3 are designed to keep synced with the coach's calendar for session scheduling. The workflows include:

  • Checking for availability

  • Scheduling a session

  • Getting updates to events

Checking for Availability

Clients, coaches, or even admins can check for availability against an external connected calendar when scheduling sessions. This is important so that events are not created that overlap with existing events for the coach.

Requesting Availability from the Coach's Calendar(s)

The availability flow request free/busy data from the calendar to find available time slots. These time slots are then presented in the Availability Dialog for selection.

Scheduling a Session

When the appropriate time slot has been selected, the session can be scheduled. When a session is scheduled, events will be created on the coach's calendar. Notifications will also be sent to the coachee via email for the event. If the coach has a primary calendar (please see this related article), then the coach's calendar will also directly send an invitation to the coachee.

Creating an Event on the Coach's Calendar(s)

In the diagram above, the event information is sent to the coach's calendar. This requires write access to be able to create the events.

Getting Updates for Events

It is possible for coaches to make updates to their external calendar events. For example, they may update the date or time of the session. In this cases it is important that the updates are made to the information in, and that the coachee is updated effectively. In this case Nylas will send webhooks indicating that a specific event has been updated and passes the ID. matches the ID to sessions on the platform and will lookup the event information to see what has changed (Date, time, etc). The information is reflected on and also attendees of the session are updated accordingly. This requires read access to the events on the calendar.

Connecting a Calendar

Coaches can connect as many calendars as they need. To connect a calendar, a coach must authorize the connection via what is called an Oauth flow. In short this means that the coach logs into their calendar and grants permission to for access. This user workflow is all managed within the application.

Coaches can connect their calendar by following the instructions in this guide:

When connecting a calendar the coach is granting permission for to access that calendar. There are required permissions in order to support the workflows describe above.

Permissions Required for Microsoft Calendars

Permissions Required for Google Calendars

Non-sensitive Scopes

Sensitive Scopes

Some organizations that use Microsoft (Outlook, Exchange, Office365), may have permissions that are controlled through an IT Administrator within your team. There are specific instructions for providing organization-wide approval (Admin consent). Instructions for providing this approval can be found in the following article:

Did this answer your question?