Authorization & Authentication

There are three main entities related to authentication in the Cronofy API model.

Application - describes your application in the Cronofy API.
Account - contains one or more related calendar connections (Profiles).
Service Account - used to interact with calendar services at organization level rather than as a user.

This article will walk you through the key concepts and is an important read for anyone building applications that leverage the Cronofy API.

You should also review the article about Permissions to understand how permissions are modelled in Cronofy.

Cronofy uses OAuth2 as a model for much of its authorization.

Applications #

Applications are created in the Developer Dashboard. Each Application is assigned the following credentials:

client_id - a public key that identifies your application. This is safe to share, for example with Cronofy support if you need assistance.
client_secret - a private key that also identifies your application. This is NOT safe to share, even with Cronofy support.

You can create as many Applications as you need. We recommend creating separate applications for your working environments, eg: development, staging, production.

If the client_secret for a production application, where real personal calendar data is accessed, is compromised you should contact support@cronofy.com immediately to have it reset.

Accounts #

The primary type of Account is one that is created when a user first authorizes your application to connect to their calendars. There are however other types that are described below.

Every Account has a sub value that is the canonical identifier for the Account in the Cronofy API. This is permanent for an Account.

When your Application obtains access to an Account it is issued with a set of credentials that are specific to the authorization. This is the authorization between your Application and the Account and is not the same as any tokens Cronofy uses to access a user’s calendars.

access_token - a short-lived, unique key that identifies your Application’s authorization to access the Account.
refresh_token - a semi-permanent, unique key that is used to obtain a new access_token when one has expired.

You should store the sub, access_token and refresh_token for each Account that you have access to.

Check out our FAQ page explaining why an access_token expires and how you can refresh it.

Calendar Accounts #

The first time a user authorizes an Application using Cronofy to access their calendar an Account is created. This Account will have one Profile representing the calendar service connected to, Google, Exchange, etc. Within the Profile there will be one or more Calendars.

The Individual Connect authorization process drops a cookie in the user’s browser. This means that sending them through the Individual Connect flow a subsequent time to connect an additional calendar service will automatically create a new Profile on the user’s Account. Your Application will then be able to access all of the user’s calendars through that one Account.

See Why do I get the same account_id and refresh_token for different users? for more information if you’re having trouble with Profiles linking to Accounts.

You can revoke access at both Profile and Account levels.

Revoking a Profile - stops your application from being able to access that Profile but does not remove it from the Account.
If you want the Profile to be removed from the Account please contact support@cronofy.com.
Revoking an Account - stops your application from accessing any data associated with that Account. It also means the user will have to reauthorize your Application to access their calendar if you want to access it again.

Delegate Calendar Accounts #

These are Calendar Accounts where the access is provided to Cronofy through another Account. The type of Account depends on the authorization method:

Business Connect uses the Profile of another Calendar Account as the credentials for accessing calendar data for a user.
Enterprise Connect uses a Service Account as the credentials for accessing calendar data.

Delegate Calendar Accounts can be used in exactly the same way as Calendar Accounts. The only difference is the credentials used to access a user or meeting room’s calendar data.

Application Calendars #

These are single purpose Accounts for situations where you want to track events but do not have a calendar service to use. They can be created on demand. They are automatically created with one Profile containing one Calendar.

They are designed to be used interchangeably with any other Account across the range of Cronofy APIs.

Service Accounts #

Service Accounts are created as part of the Enterprise Connect authorization flow. They serve two purposes:

Listing the Resources available in a domain.
Generating Calendar Accounts for users and resources.

They do not have Profiles attached and thus cannot be used as conventional Accounts in the Cronofy API, i.e. for reading Events.