Business Connect ^PRERELEASE

We’ve taken a deliberate decision with the Cronofy authorization model to not allow applications to automatically get access to calendars that are shared with the user connecting. Our view is that whilst a colleague may have shared their calendar with a user, that user shouldn’t be implicitly sharing that calendar with any application.

This represents a potential breach privacy that runs counter to the standards of personal data protection that we work to. However, there are situations where accessing those calendars is desirable.

Whilst Enterprise Connect allows access to potentially any calendar in an organization’s domain it has a setup overhead which is untenable for many applications.

Business Connect allows an application to leverage the implicit and explicit permissions models enabled within organizations through calendar sharing.

Authorizing The Primary Account #

From an end-user perspective, we’ve implemented Business Connect as an extension to the Individual Connect authorization flow.

Your application will request access to the primary user’s calendar account using the standard OAuth2 redirect process. But, you’ll add an additional parameter called delegated_scope to the query string. This indicates the permissions you are requesting on the shared calendars.

The authorization is completed in the same way as for Individual Connect

Authorizing Delegate Accounts #

A delegated access model is used to get generate Cronofy Accounts and get authorization for each of the additional calendars. The Primary Account is used as the master access for generating these Delegate Accounts.

You will need three values in order to get access to another Account.

• access_token for the Primary Account.
• profile_id for Profile of the the primary user Account that has access to the Delegate Account.
• email of the Delegate Account

Your Application provides these to Cronofy in order to obtain access.

The API request is made as follows.

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

{
    "profile_id": "{PRIMARY_USER_PROFILE_ID}",
    "email": "{EMAIL_OF_ACCOUNT_TO_ACCESS}",
    "callback_url": "{CALLBACK_URL}",
    "scope": "{SCOPES}",
    "state": "{STATE}"
}

This is an asynchronous process so you won’t receive the tokens back straight away.

When the Delegate Account has been validate and onboarded into Cronofy, your application will receive a callback at the CALLBACK_URL you specified, similar to this:

POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "authorization": {
    "code":  "{CODE}",
    "state": "{STATE}"
  }
}

We’ve implemented this as a headless OAuth2 flow so you then redeem the code for the Account information in the same way you did for the Primary User Account. And will get the following for the newly authorized Account.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-store
Pragma: no-cache

{
  "token_type": "bearer",
  "access_token": "P531x88i05Ld2yXHIQ7WjiEyqlmOHsgI",
  "expires_in": 3600,
  "refresh_token": "3gBYG1XamYDUEXUyybbummQWEe5YqPmf",
  "scope": "read_only",
  "account_id": "acc_5ba21743f408617d1269ea1e",
  "sub": "acc_5ba21743f408617d1269ea1e",
  "linking_profile": {
    "provider_name": "google",
    "profile_id": "pro_n23kjnwrw2",
    "profile_name": "example@cronofy.com"
  }
}

And that’s it. You now have an Account you can use with access to the information for that user. If you need more Accounts you just repeat the flow for each user.

See the full Business Connect docs for more information.

Discovering Accounts To Delegate #

The Accessible Calendars endpoint gives a list Calendar Accounts that should be accessible from the Primary User Account.

It must be stressed that the output of this is not a definitive list. The Primary User Account may be able to access more calendars than appear in this list. Known behaviour:

Google Workspace #

This should return both the rooms a user has access to as well as the list of accessible calendars from My Calendars in the Calendar UI.

Exchange/Office 365 #

This will only contain a list of resources if the a room list has been configured by the IT Admin. It will not contain the list of People Calendars defined in Outlook.