Free/Busy Only

There are two ways to connect calendars through Enterprise Connect where only Free/Busy information is shared with Cronofy. Which one applies depends on the calendar provider your user is connecting with:

Free/Busy only for on-premise Exchange #

Pre-requisites #

In order to make use of Enterprise Connect with Free/Busy only calendars you must first request access to the feature by contacting us at support@cronofy.com.

You must be running an on-premise Exchange server and have configured a service account with the correct access rights to the target calendars.

Example: granting the AvailabilityOnly folder permission to a service account via Powershell

Add-MailboxFolderPermission -Identity professional@example.com:\Calendar -AccessRights AvailabilityOnly -User service_account@example.com

For more detail on configuring the service account, see Configuring Free/Busy only access.

Authorization process #

The authorization process differs slightly from a calendar with full access rights: you must request only the free_busy scope when Requesting Delegate Access to a calendar.

Please note that the service account’s delegate scope must include free_busy in order to authorize this scope. The service account may also have additional delegate scopes.

Should any additional scopes be requested (for example read_events) and the service account be unable to read events from the Exchange server, you will receive an unable_to_grant_scope error in the callback.

To help you diagnose these errors we have made the errors viewable on the Enterprise Connect section of your Developer dashboard. In addition to this we can also expose the Exchange validation logs via the Developer dashboard to diagnose your connectivity issues. Again, please contact support@cronofy.com to request access to this.

A simple way to test that the access has been granted correctly is to make these calls and validate the callback has no error.

Account differences #

As the only scope these accounts can be granted is free_busy, they are read-only: your application cannot create events in the user’s calendar.

To identify a Free/Busy only account, make a call to the UserInfo endpoint and check that cronofy.type is free_busy_only.

In addition, listing the calendars for a Free/Busy only account will return a single read-only calendar named Free Busy.

Free/Busy Calendar Access Mode for Google Workspace and Microsoft 365 #

For Google Workspace and Microsoft 365, free/busy only connections are made using the Free/Busy Calendar Access Mode.

Cronofy reads availability from the user’s primary calendar but cannot see event details. Unlike the on-premise Exchange approach above, your application can still create and update events. They are delivered to the user as email invites rather than written directly into their calendar.

Required Scope: service_account/accounts/manage

Required Delegated Scope: free_busy_write

Required Feature: Enable Free/Busy in the Features section for your application in the Cronofy Developer Dashboard.

Requesting service account authorization #

Follow the standard Enterprise Connect flow, specifying free_busy_write as the delegated_scope and free_busy as the access_mode when requesting service account authorization.

    https://app.cronofy.com/enterprise_connect/oauth/authorize
    ?response_type=code
    &client_id={CLIENT_ID}
    &redirect_uri={REDIRECT_URI}
    &scope=service_account/accounts/manage
    &delegated_scope=free_busy_write
    &access_mode=free_busy
    &state={STATE}

You can also pass provider_name as an optional request parameter to take the person authorizing the service account straight to a specific provider. The following Free/Busy providers are supported:

• google_free_busy
• ms_graph_free_busy

Requesting user and resource access #

Once you have a service account authorization, request access to individual users and resources as normal via Request User/Resource Access, specifying the free_busy_write scope.

POST /v1/service_account_authorizations HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {SERVICE_ACCOUNT_ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
    "email" : "{EMAIL_OF_DELEGATED_ACCOUNT}",
    "callback_url": "{CALLBACK_URL}",
    "scope" : "free_busy_write",
    "state": "{STATE}"
}

Account differences #

Accounts connected this way report a provider_name and provider_service of google_free_busy or ms_graph_free_busy from the UserInfo endpoint, and in the linking_profile returned by Request an Access Token.

Event details are not available, so Read Events reflects only events your application created. Use Read Events with Free/Busy information and the Availability API for the user’s availability.

Administrator setup #

The corresponding guides for the customer’s IT administrator are:

• Microsoft 365: Free/Busy Calendar Access Mode
• Google Workspace: Free/Busy Calendar Access Mode