Authentication

There are two forms of authentication within the Cronofy API. Broadly speaking this is split into two categories

  1. Authenticating as a specific user - ACCESS_TOKEN
  2. Authenticating as an application - API_KEY

The form required depends on the endpoint, and they are not interchangeable. When representing something owned or specific to a user, the ACCESS_TOKEN is used for User Authentication. For items which do not always have a link to a user, or which are shared by multiple users, the API_KEY is used for Application Authentication.

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}

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 the Bearer token.

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

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.