Enterprise Connect - Delegated Access

How to obtain access to end-user and resource calendars using our Enterprise Connect feature.

Enterprise Connect works by your application first obtaining a pre-authorization for your application to access the calendars for a domain. This uses a special type of account called a Service Account (see What is a Service Account for a primer on Service Accounts).

Permissions for Delegated Access

Part of the process of obtaining pre-authorization requires that your application specifies the permissions it will request. This is done through the delegated_scopes parameter.

This should be the maximum set of permissions your application will need on any user or resource calendars.

Requesting Delegated Access

This process is similar to an OAuth2 flow you would use to obtain authorization from an end-user but, importantly, it removes the need for end-user involvement and thus has no UI. This is possible because your application has already obtained pre-authorization using a Service Account.

1. Make The Request

The request for access looks like the following.

POST /v1/service_account_authorizations HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8
Authorization: Bearer {ACCESS_TOKEN_OF_SERVICE_ACCOUNT}

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

The scope needs to be a subset of the scopes requested in the delegated_scope parameter during the Service Account authorization. For example you will not be able to request read_events if you delegated_scope only included read_free_busy .

The Cronofy API accepts this request and then asynchronously attempts to obtain access to the the calendar for the Delegated Account. The result of this process is returned as a web hook to the callback_url provided.

The callback_url needs to be publicly accessible. Whilst you're developing, we recommend using a tool like ngrok to generate temporary public urls that will pass straight through to your development machine.

2. Receive The Code

The callback_url will then receive a web request similar to the following.

POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8

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

The code is a one-time use code for then obtaining access credentials for the Delegated Account.

The state parameter is the same value your application passed in Step 1 and thus can be used to contain any user identification information.

Pro-Tip - When you're running ngrok you can access all the requests via http://localhost:4040/. Even better, you can replay them at will. Great when you're developing callback end points.

3. Obtain Access Credentials

Once you have the code you can then redeem it for an access_token and refresh_token for the Delegated Account.

POST /oauth/token HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "grant_type": "authorization_code",
  "code": "{CODE}",
  "callback_url": "{CALLBACK_URL}"
}

Importantly these credentials for Delegated Accounts act just like a normal, end-user authorized, Account. This means you can refresh and/or revoke them in the usual way.