Extended Permissions

Description #

As an extension of the OAuth flow users can be asked to grant unrestricted access to their calendars. This is implemented through a redirect to an additional access page.

This process comprises of the following steps:

1. User is taken through normal OAuth flow and grants access to Cronofy
2. Your application obtains its OAuth access tokens as before
3. Your application issues a request for a list of calendars for the user using the OAuth tokens
4. Your application issues a request to elevate permission for your selected calendars (from the list of calendars retrieved) along with a redirect URL
5. Cronofy will respond with a payload including a URL to redirect the end user to grant or reject your requested access
6. The user will accept or reject the additional permissions and will be redirected back to application via the redirect URL provided

To the user there will be a single additional step but as that step happens after you have your OAuth access tokens we do not expect this step to reduce conversion in calendar connection.

URL format #

{data_center_url}/v1/permissions

Example Request #

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

{
    "permissions": [
        {
            "calendar_id": "cal_n23kjnwrw2_jsdfjksn234",
            "permission_level": "unrestricted"
        }
    ],
    "redirect_uri": "http://www.example.com/permission"
}

Example Response #

For accounts which are not linked to an Enterprise Connect account.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "permissions_request": {
        "url": "https://app.cronofy.com/permissions"
    }
}

The user should be redirected to the given URL in order to grant you elevated access to the calendars you specified.

For accounts linked to an Enterprise Connect account there is no URL returned, instead the permissions are granted as a result of the request.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "permissions_request": {
        "accepted": true
    }
}

Request parameters #

permissions required  #

Multiple calendar_id’s can be provided in the permissions array, the only acceptable value for permission_level is unrestricted, further options may be added in future.

redirect_uri required  #

The redirect_uri is the page which the user will be directed to after they have granted or rejected permission.

Note that if the user rejects the request a query string value of error=access_denied will be added to the URL before they are redirected to it.