Application Authorization

How to obtain authorization from your users to access their calendars.

This guide will get you started with how to obtain authorization to access your users’ calendars.

Cronofy sits as an intermediary layer between your application and your users’ calendars. This means that your application is actually authorizing with Cronofy rather than directly with the calendar services. We handle the different calendar service authorizations processes so you don’t have to.

In order to do this we utilise the same OAuth2 security protocol that Google use. The high level process is:

  1. Your app sends the user to a Cronofy hosted authorization page, specifying the permissions you need on their calendars
  2. The user approves access by logging into their chosen calendar service
  3. The user is redirected back to your app with a query string that contains a code
  4. Your app redeems that code for an access_token and refresh_token that allows your application the requested access to that user’s calendars.

Now to walk you through setting up this flow.

Setting Up the Auth Flow

IDENTIFYING YOUR APPLICATION

The first step is to identify your application to Cronofy. This will give you the CLIENT_ID and CLIENT_SECRET required by the process.

Login to the Developer Dashboard and choose Create application from the dropdown.

This will give you the CLIENT_ID and CLIENT_SECRET you need.

You’ll note that there is a warning that This application is not verified. We’ll explain this later on this guide but for the moment it’s just a warning and is not going to prevent you from getting up and running.

GAINING THE USER’S APPROVAL

Now we’ve got the identifiers needed for the application we can now setup the redirect flow. The URL to send your users to is constructed as follows.

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

  • CLIENT_ID is the one associated with your app created above
  • REDIRECT_URI the URL we should redirect the user to once they’ve completed the authorization
  • SCOPE is the space separated (%20 on a URL string) list of permissions you’re requesting. Full docs here: Request Authorization Docs
  • STATE this is returned, unaltered, on the query string when the user is redirected back to your app.

See the Request Authorization docs.

GETTING THE ACCESS TOKEN

When the user is redirected back to your application the query string will contain a codeparameter. This is a one time use code used to retrieve the access_token and refresh_tokenfor the user.

If you’re using a library for managing the OAuth flow then it is likely that it will handle this step for you as we’ve followed a series of conventions for the various token management endpoints. For example

  • omniauth for ruby automatically retrieves the tokens as part of populating it’s credential hash.
  • DotNetOpenAuth as the RequestUserAuthorization on the WebServerClient for retrieving the tokens
  • OAuth2 Client for PHP provides $provider->getAccessToken() for this purpose.

If you need to retrieve the code yourself, then the Request Access Token docs will give you what you need.

USING THE ACCESS TOKEN

The final step is to use the access_token to interact with the user’s calendars.

It is passed in an Authentication header in all HTTP requests to the API.

GET /v1/calendars HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

More information in the Authorization section of our API docs.

Verifying Your Application

Calendar data is sensitive data so we need to do what we can to ensure that we’re only passing codes back to your application.

We do this by only allowing verified applications to request authorization using pre-configured redirect_url values.

Once your app is ready for production then let us know the URL(s) you’ll be redirecting the users to after they’ve authorized by emailing support@cronofy.comand we can get your application verified.

Dealing With A Token Expiry

One more thing to consider is handling token expiry. You will need to deal with it some point as access_tokens are designed to expire periodically.

This is the purpose of the refresh_token return alongside the access_token. If you store that against your user record as well then you can use it to request a new access_token at any time.

Again OAuth2 libraries generally have support for this flow.

See the Refresh Access Token docs.