Delegated Access

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.

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: {data_center_url}
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 your delegated_scope only included read_free_busy.

The Cronofy API accepts this request and then asynchronously attempts to obtain access to 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 endpoints.

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: {data_center_url}
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.