Developer FAQs

If you have any questions that aren’t covered here or need any help with using the API, don’t hesitate to email us or post a question to our API Mailing List.


Why do I have to verify my application in order to move from Development Mode to Production Mode?

Calendar data can be incredibly sensitive so we need to be as sure as possible that when we receive an authorization request from your application, that we don’t pass authorization codes back to an application with nefarious intent.

In order to do this, we store one or more of the redirect_uri you will be using with the authorization process. We then validate any requests that come against this redirect_uri whitelist to ensure we’re only redirecting and thus passing codes to your application.

When you’re ready to verify your application. Email support@cronofy.com with a list of URIs and we can add them.

NB: we don’t support wildcards in the URIs. While we do support more than one URI for an application, we would recommend setting up separate applications for each of your development, staging and production environments.


Are push notifications secured or authenticated in any way?

We don’t pass any authentication credentials with the notifications. We’ve allowed the callback_url to differ between notification channels (some APIs require it be fixed for all channels) so that you may embed some form of authentication token within the URL if you want an extra layer of security.

On top of requiring a valid OAuth token to create a notification channel in the first place, we can also whitelist domains that can be used for the callback URL. We also encourage the use of HTTPS in production, even though we’ve deliberately kept the notifications themselves free of sensitive information.


How do I know which of my users a push notification relates to?

When you create a channel for push notification we recommend you include an identifier in the callback_url. So instead of having one URL for all callbacks like,

https://api.company.com/cronofy_callback

you would instead set the callback URL to be something like

https://api.company.com/cronofy_callback/{user_id}

We recommend using something non-sensitive as the identifier like an internal, non-guessable ID.


Why aren’t the events I create there when I read a user’s events?

By default we don’t return events your application has created when you query the Read Events endpoint.

If you add the include_managed parameter when requesting we will return your events as well.

We differentiate between managed events (that your application creates) and un managed events (that are created outside of your application) to streamline much of the interactions with our API.

With this particular default behaviour decision we worked on the premise that the application was the source of truth of managed events and thus would not want to receive the version of those events from the user’s calendar by default.


Why do I keep getting errors.unknown_or_used when requesting an access_token?

The codes that are generated when a user goes through the authorization process are restricted in a number of ways. This error means one of two things:

1. The code has expired or has already been used

Codes are single use codes that expire in a relatively short time frame. So when if you’re building an auth flow from scratch and not using something like Omniauth, you will need to be careful to request a new code each time you want to test your access_token redemption process.

2. The information passed when redeeming the code doesn’t match the authorization values.

The most common cause of this is that redirect_uri value passed to Request Access Token doesn’t match that used in the Authorization Request.

You can inspect the token request in your Developer Dashboard and cross reference that against the preceding authorization request

These restrictions help to ensure that codes don’t end up in the wrong hands.


Do you allow us to white label the authorization screens?

We support some customization of the authorization screens for customers on our Growth Plan. This allows you to replace the header of the auth page with a logo or image of your choice and the Cronofy branding moves to the footer.

If you’d like to have this setup for your application, please contact support@cronofy.com.


What does the auth flow look like?

We’ve streamlined the auth process to ensure the user has to make as few steps as possible which keeping them informed.

The process is initiated by your app sending the user to the auth request URL:

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

For more info see API docs – Authorization.

In this example we’ve used our demo company Evenitron as the API integrator.

STEP 1. CHOOSE CALENDAR PROVIDER

Scopes and authorization request is confirmed in one step.

Oauth step 1

STEP 2. LOG IN

Dedicated sign up dialog or link depending on the calendar service the user requests. In this case the user has chosen Apple iCloud.

Oauth step 2

STEP 3. THERE IS NO STEP 3

At this stage the user is redirected back to your application and you can then request a persistent access token from the API.


Can I use my own event IDs?

We don’t issue IDs to events, instead we require that developers provide an event_id when upserting an event to a user’s calendar. This is then used to identify the event when making subsquent updates/deletes.

This ID must be unique within the scope of your application’s client_id.

The rationale for this is two-fold.

  • When inserting an event, your application doesn’t have to block, waiting for a response from a third-party system in order to receive the ID.
  • Your system doesn’t have store any mapping between your internal IDs and external IDs

Why do I get a CORS error : “No ‘Access-Control-Allow-Origin’ header is present on the requested resource”?

If you try to pass an access_token (either personal or generated from an authorization exchange) from a browser XMLHttp request for example you will receive an error

 No 'Access-Control-Allow-Origin' header is present on the requested resource 

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources (e.g. fonts) on a web page to be requested from another domain outside the domain from which the resource originated.

We’ve deliberately not enabled CORS because it would enable/encourage access and refresh tokens to be passed to the browser where they could be much more easily compromised.

For example, someone uses he capability to write a WordPress plugin for a blog which entails sending the access and refresh token to the browser That works, people install it, now anyone can view source on that site and have at least some level of read access to that persons calendars.

In order to resolve this you will need a server component that handles the API interactions with Cronofy and then renders the required information to the browser.