Organization Connect

Required plan: None

Organization Connect allows your application to obtain authorization to access your users’ Cronofy accounts. This authorization model differs to Individual Connect and Enterprise Connect in that instead of just giving access to raw calendar accounts, your application also gets access to your users’ Cronofy Organizational Unit configuration and capabilities.

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 at the foot of the page.

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 Your 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. The initial scope available is organizational_unit_scheduler

  • STATE this is returned, unaltered, on the query string when the user is redirected back to your app.

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 Cronofy Organizational Unit.

It is passed in an Authorization header in all HTTP requests to the API as a Bearer token. When using API calls that interact with the Organizational Unit, eg: Organizational Unit Members this is all you need.

For all requests that pertain to a specifics users, eg: Create or Update Event, an additional Cronofy-Impersonate header is used to identify the user.

GET /v1/userinfo HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Cronofy-Impersonate: {USER_SUB}

The user sub can be resolved by email address by using the Organizational Unit Members end-point.

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.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.