Request Authorization

In order to perform actions on behalf of a user, they must first authorize you to do so.

Authorization is received by performing the “Authorization Code” version of authorization as specified in section 4.1 of RFC 6749.

This will issue you a short-lived, single-use code that you will be able to exchange for an access_token and refresh_token for the user.

Example request URL #

The parameters are encoded in the querystring as specified in appendix B of RFC 6749. Additional linebreaks are added to the request’s path for clarity.

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

Request URL parameters #

response_type required  #

Must always be code as that is the only grant type supported by Cronofy.

client_id required  #

The client_id issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client.

redirect_uri required  #

The HTTP or HTTPS URI you wish the user’s authorization request decision to be redirected to.

scope required  #

The scope of the privileges you want the eventual access_token to grant. At least one of the following simplified or standard scopes must be requested:

Simplified scopes

Simplified scopes support common use cases. They have a simplified description for the end user and are equivalent to requesting multiple standard scopes.

Please note that simplified scopes cannot be used together with standard scopes. If this is required then the equivalent standard scopes should be used.

• read_only to allow Read Events and Free/Busy requests. This scope is equivalent to read_events and read_free_busy scopes.
• write_only to allow Create Calendar, Create or Update Events and Delete Event requests. This scope is equivalent to create_calendar, create_event, and delete_event scopes.
• read_write to allow all requests mentioned in read_only scope and write_only.
• free_busy to allow Free/Busy requests. This scope is equivalent to read_free_busy scope.
• free_busy_write to allow all requests mentioned in free_busy scope and write_only. This scope is equivalent to create_calendar, create_event, delete_event, and read_free_busy scopes.

Standard scopes

Standard scopes allows for a more tailored approach. These scopes can be combined depending on the privileges your application needs.

• create_calendar to allow Create Calendar requests.
• read_events to allow Read Events requests.
  • Note that if you only want to read the events you are managing, you do not need this scope so long as you pass a only_managed parameter of true to Read Events and Create Notification Channel requests.
• create_event to allow Create or Update Event requests.
• delete_event to allow Delete Event requests.
• read_free_busy to allow Free/Busy requests.
  • Note that the read_events scope implicitly includes this scope as it allows access to a higher level of information than free/busy so you do not have to request both.
• change_participation_status to allow the Participation Status of a user in an event to be set. The format of this value is specified in section 3.3 of RFC 6749 but is a space-separated String of named scopes, e.g. read_events create_event delete_event.

state optional  #

A value that will be returned to you unaltered along with the user’s authorization request decision.

The OAuth 2.0 RFC recommends using this to prevent cross-site request forgery.

code_challenge optional  #

A parameter used to protect against an authorization code intercept attack defined in RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients.

Providing this value will mean that a corresponding code_verifier parameter must be provided when redeeming an authorization code for an access_token.

code_challenge_method optional  #

Describes the method used to verify the code_verifier parameter that will be sent when the access_token is requested. Two values are supported.

• S256
• plain

If not passed then plain is the default used if a code_challenge parameter is provided.

avoid_linking optional  #

A Boolean value that when true means we will avoid linking calendar accounts together under one set of credentials.

If not provided, defaults to false.

By default, requesting authorization ties the calendars linked by the same browser to one account. This allows you as the developer to be able to access all of the users calendars through one set of API credentials.

However, your users may sometimes use a shared computer and so you may not want the calendar accounts to be tied together. This is the kind of situation in which you would want to specify this parameter as true and we will then create a set of credentials for each calendar linked.

locale optional  #

A String value for the locale to use for display purposes. If not provided we will use the locale provided by their browser. In general you will not want to supply this and instead rely on the user’s browser to provide the correct locale.

Currently supported locales are:

• ar Arabic
• cs Czech
• cy Welsh
• de German
• en US English (default)
• es Spanish
• fr French
• fr-CA Canadian French
• he Hebrew
• it Italian
• ja Japanese
• nl Dutch
• pl Polish
• pt-BR Brazilian Portuguese
• ru Russian
• sv Swedish
• tr Turkish
• zh-CN Simplified Chinese

provider_name optional  #

A String value indicating a calendar service provider to pre-select for the user.

Currently supported options are:

• apple Apple iCloud
• exchange Microsoft Exchange
• google Google Workspace and personal Google
• live_connect Outlook.com, includes Hotmail and Live
• office365 Office 365

Response URL parameters #

You will not receive a direct response to your Authorization Request, instead the user will be redirected to the REDIRECT_URI with additional querystring parameters specified.

The responses are fully specified in section 4.1.2 of RFC 6749.

Successful response #

code  #

A short-lived, single-use code to be used to make an Access Token Request.

Will always be 32 character String of ASCII characters.

state  #

The value you passed for the state within the authorization request.

Error response #

error  #

A single ASCII error code. The complete list is within section 4.1.2.1 of RFC 6749, these are the most commonly encountered:

• access_denied the user declined your request
• unsupported_response_type your request’s response_type was not code
• invalid_scope no valid scopes were specified in your request’s scope