Authorization & Authentication

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

Application - describes your application in the Cronofy API.
Organizational Unit - holds a company’s members, their calendars, and its scheduling configuration.
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 a client_secret is compromised, generate a new one and stop accepting the old one from the application’s Credentials page. See Refreshing Client Secret.

Organizational Units #

An Organizational Unit is a container for a company’s, or part of a company’s, use of Cronofy: its members, their connected calendars, and its scheduling configuration, such as Selection Rules and Templates. It’s also a hard permissions boundary, so nothing in one Organizational Unit is visible from another.

How your application gets access to an Organizational Unit depends on your integration approach:

An Internal Application is linked to your own company’s Organizational Unit, and authenticates with its client_secret.
An application your customers use is authorized for each customer’s Organizational Unit through Organization Connect, and keeps a separate access_token and refresh_token for each one. A company with more than one Organizational Unit authorizes each separately.

Your application can act as an individual member of an Organizational Unit by passing their sub in the Cronofy-Impersonate header.

Organizational Unit structure covers how companies typically divide themselves into Organizational Units.

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.