# Free/Busy Access

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](https://docs.cronofy.com/api-reference/calendar-control/calendar-events/upsert-event/index.md) 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
> **INFO:** To enable this feature you will need to toggle it on in the Features section for your application in the Cronofy developer dashboard.

### Individual Connect
**Required Scope**: `free_busy_write`

This mode follows the same steps as the [Individual Connect](https://docs.cronofy.com/developers/temporal-grid/connectivity/individual-connect/index.md) flow which includes specifying the `free_busy_write` scope when [requesting authorization](https://docs.cronofy.com/api-reference/authorization/individual-connect/request-authorization/index.md).

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

<br>
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](https://docs.cronofy.com/developers/temporal-grid/connectivity/individual-connect/index.md).

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 Scope**: `service_account/accounts/manage`

**Required Delegated Scope**: `free_busy_write`

Cronofy reads availability from each user's primary calendar but can't see event details. Your application can still create and update events, which are delivered to the user as email invites rather than written directly into their calendar.

#### Requesting service account authorization
Follow the standard [Enterprise Connect](https://docs.cronofy.com/developers/temporal-grid/connectivity/enterprise-connect/index.md) flow, specifying `free_busy_write` as the `delegated_scope` and `free_busy` as the `access_mode` when [requesting service account authorization](https://docs.cronofy.com/api-reference/authorization/enterprise-connect/request-authorization/index.md).

```
    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}
```

<br>
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`

> **INFO:** Take care not to confuse `access_mode` and `delegated_scope`.

`access_mode` determines the level of access *Cronofy* will have to the connected calendars.

`delegated_scope` determines the level of access *your application* will have against those calendars.

#### 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](https://docs.cronofy.com/api-reference/authorization/enterprise-connect/delegated-access/index.md), 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}"
}
```

<br>
#### 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](https://docs.cronofy.com/api-reference/fundamentals/identity/userinfo/index.md), and in the `linking_profile` returned by [Request an Access Token](https://docs.cronofy.com/api-reference/authorization/individual-connect/request-token/index.md).

Event details are not available, so [Read Events](https://docs.cronofy.com/api-reference/calendar-control/calendar-events/read-events/index.md) reflects only events your application created. Use [Read Events with Free/Busy information](https://docs.cronofy.com/api-reference/calendar-control/calendar-events/free-busy/index.md) and the [Availability API](https://docs.cronofy.com/api-reference/availability-control/availability/index.md) for the user's availability.

#### Administrator setup
The corresponding guides for the customer's IT administrator are:

- [Microsoft 365: Free/Busy Calendar Access Mode](https://docs.cronofy.com/connect/calendar-admins/enterprise-connect-office365-graph/free-busy-access-mode/index.md)

- [Google Workspace: Free/Busy Calendar Access Mode](https://docs.cronofy.com/connect/calendar-admins/enterprise-connect-gsuite/free-busy-access-mode/index.md)

## Free/Busy only for on-premise Exchange
Free/Busy Access mode is available for Google and Microsoft 365. On-premise Exchange calendars can instead be connected through Enterprise Connect with a service account that can only see free/busy information. Your application can't create events in these calendars.

### 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](mailto: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](https://docs.cronofy.com/connect/calendar-admins/enterprise-connect-office365-exchange/free-busy-access/index.md).

### 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](https://docs.cronofy.com/api-reference/authorization/enterprise-connect/delegated-access/index.md) 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](https://docs.cronofy.com/api-reference/authorization/enterprise-connect/delegated-access/index.md).

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](mailto: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](https://docs.cronofy.com/api-reference/fundamentals/identity/userinfo/index.md) 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`.

## 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:

- [Read Events with Free/Busy information API](https://docs.cronofy.com/api-reference/calendar-control/calendar-events/free-busy/index.md)

- [Availability API](https://docs.cronofy.com/api-reference/availability-control/availability/index.md)

## Custom Emails For Event Invites
When using the Free/Busy Access Mode, the invite emails the end user receives will come from a Cronofy email by default.
It's possible to set up a custom email for these email invites.

- [Custom Emails For Event Invites](https://docs.cronofy.com/developers/calendar-and-availability/access-modes/custom-emails-for-event-invites/index.md)



---
[Read in HTML](https://docs.cronofy.com/developers/calendar-and-availability/access-modes/free-busy/)