Free/Busy Access ALPHA

Required plan: Emerging

Users connecting their calendars via the Free/Busy Access mode means your application will only be able to see whether a user is free or busy for events synced from their calendar, instead of accessing the full event details.

When a user connects via this mode, new events and updates are not written directly to the calendar when you make a Create or Update event API call. Instead, they are delivered via an email invite and once they accept the invite, their email client will add the event to their calendar.

This allows users to enjoy the benefits of a Cronofy integration without granting full access to their calendar.

Free/Busy mode is currently available for Google and Microsoft Office 365 accounts.

Connecting a user in Free/Busy mode #

Individual Connect #

Required Scope: free_busy_write

This mode follows the same steps as the Individual Connect flow which includes specifying the free_busy_write scope when requesting authorization.

    https://app.cronofy.com/oauth/authorize?response_type=code
      &client_id={CLIENT_ID}
      &redirect_uri={REDIRECT_URI}
      &scope=free_busy_write
      &state={STATE}

You can also pass provider_name as an optional request parameter. The following Free/Busy providers are supported:

  • google_free_busy
  • ms_graph_free_busy

This will direct the user to the authorization page for the specific Free/Busy provider without offering them other provider options.

This will direct the user to verify their Google or Office 365 account and return the code as described in Getting the Access Token.

Once access has been been granted by the user, we will be able to send invite emails to the, allowing you to use the Cronofy APIs for this account as usual.

Enterprise Connect #

Required Delegated Scop: free_busy_write

Required Scope: service_account/accounts/manage

This mode follows the same steps as the Enterprise Connect flow which includes specifying the free_busy_write scope 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
    &state={STATE}

Then once you have a Service Account authorization, you follow the same steps as the Request User/Resource Access flow which includes 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}"
}

This will return the code to be used to obtain an Access Token as described in Receive the code.

Once access has been been granted on behalf of the user, we will be able to send invite emails to them, allowing you to use the Cronofy APIs for this account as usual.

Requesting Event Information #

When using the Free/Busy access mode, you will be able to get event information on the end users calendar by using the:

  1. Read Events with Free/Busy information API
  2. Availability API

Be aware that as we create a Cronofy Calendar on the users Cronofy Account to handle any events created via Cronofy, the user will have two profiles on their account. One profile represents their Free/Busy profile they granted access too, the other profile is the Cronofy Calendar. You will need to keep this in mind when building availability queries as the most accurate result will return when you request the availability of both these profiles, not just one.