Application Authorization

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

Indentifying 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}

See the Request Authorization docs.

Getting The Access Token

When the user is redirected back to your application the query string will contain a code parameter. This is a one time use code used to retrieve the access_token and refresh_token for 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 verfied applications to request authorization using pre-configured redirect_uri 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.com and 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.

Some Example Implementations

# While this example uses Rails as the app framework, omniauth is
# designed to work with any Rack based framework
#
# Using omniauth-cronofy strategy this will create
# a redirect_url path of /auth/cronofy/callback
#
# Gemfile
gem 'omniauth-cronofy'

# omniauth.rb
Rails.application.config.middleware.use OmniAuth::Builder do
  provider :cronofy, ENV["CRONOFY_CLIENT_ID"], ENV["CRONOFY_CLIENT_SECRET"], {
    scope: "read_account list_calendars read_events create_event delete_event"
  }
end

# routes.rb
  get "/auth/:provider/callback", to: "auth#callback"

# auth_controller.rb

  def callback
    case auth_hash['provider']
    when 'cronofy'
      user = User.find_or_create_by(cronofy_id: auth_hash['uid'])
      user.cronofy_access_token = auth_hash['credentials']['token']
      user.cronofy_refresh_token = auth_hash['credentials']['refresh_token']
      user.save

      flash[:success] = "Connected to your calendars"

      redirect_to :root
    end
  end

  def auth_hash
    request.env['omniauth.auth']
  end
end

Join our developer mailing list

* indicates required