Authentication

There are two forms of authentication within the Cronofy API. This differ whether you are using our White-Label API or Scheduler API.

White-Label API #

Our White-Label API gives your application the ability to embed raw calendar data and capabilities like availability queries and working hours management for your users. Authentication using our White-Label API is split into two categories.

  1. Authenticating as an application.
  2. Authenticating as a specific user.

The form required depends on the end point, and they are not interchangeable.

For end points which are not tied to a specific the API_KEY is used for Application Authentication.

When accessing endpoints that represent something owned or specific to a user, eg their calendar events, an access_token obtained through the Individual Connect or Enterprise Connect auth flows is used.

Application Authentication #

For endpoints where potentially many, or indeed no, users are involved authentication can be performed via the common authorized application. As an API client you will be issued with a client_id and a client_secret to be provided with the request to authenticate your application

This is handled by passing the client_secret as API_KEY for the Bearer token.

GET /v1/real_time_scheduling/{id} HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}

User Authentication #

For endpoints relating to a specific user, such as Read Events, authentication is performed via OAuth 2.0 tokens. As an API client you will be issued with a client_id and a client_secret to be used as specified in RFC 6749 to retrieve access tokens in order to perform actions on behalf of a user

Access Tokens MUST be passed with each API request as a Bearer Authorization header as specified in RFC 6750.

For example:

GET /v1/calendars HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}

Scheduler API #

Our Scheduler API gives your application access to a user’s Cronofy Organization Account. Allowing it to take advantage of the rules, onboarding and configuration that they have already set up in Cronofy.

Authentication using our Scheduler API is again split into two categories.

  1. Authenticating as an application.
  2. Authenticating as a specific user.

For end points that relate to the Organization, either the client_secret of and Internal Application or the access_token generated by an Organization Connect flow are used.

For end points that relate to individual users, eg Create or Update Event, alongside the Appllication Authentication token an additional Cronofy-Impersonate Header is used to identify the user.

Organization Authentication #

If your app is setup to be an Internal Application or you have obtained an Organization Connect Authorization to your a Cronofy Organization, you can access specfic end-points relating to the Organization. For example to enumerate Organizational Unit Members.

You do this by passing the client_secret as the API_KEY of the Internal Application or the access_token obtained through the Organization Connect auth process as the Bearer token.

GET /v1/organizational_unit_members HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN or API_KEY}

User Impersonation #

If your app is setup to be an Internal Application or you have obtained an Organization Connect Authorization to your a Cronofy Organization, you can impersonate individual users in that Organization.

You do this by passing the Cronofy sub for the user in a Cronofy-Impersonate HTTP Header alongside the appropriate Bearer token.

For example:

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

Error responses #

401 Unauthorized #

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

403 Forbidden #

The request was refused as the provided authorization credentials were recognized but do not grant sufficient privileges.

You will need to make an additional authorization request for the scope required for the forbidden request.