# Request Authorization
In order to perform actions on behalf of a user, they must first authorize you to do so.
> **WARNING:** When requesting authorization from a user, the domain is **app.cronofy.com** and not **api.cronofy.com** that you make the API calls to.
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
##### `data_center_app_url` *(required)*
The URL for the data center you want to communicate with. Possible choices are:
- `app-au.cronofy.com` - Australia
- `app-ca.cronofy.com` - Canada
- `app-de.cronofy.com` - Germany
- `app-sg.cronofy.com` - Singapore
- `app-uk.cronofy.com` - United Kingdom
- `app.cronofy.com` - United States
Find out more about [Cronofy's data centers](/developers/data-centers/index.md).
##### `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.
> **WARNING:** In development this can be any value, but in production this has to be a **pre-registered** value. This helps us guard against phishing attacks by controlling where we return authorization codes to for your application. We can only support wildcards in the host name for subdomains of domains under your control, eg:
`https://*.example.com/auth/cronofy/callback` Otherwise, the URL must be static and we can support multiple values. If your URL is dynamic, you should utilize the `state` parameter to pass variables. See [our FAQ on using this to support dynamic values in your OAuth flow](/developers/faqs/application-management/state-param/index.md).
##### `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](/developers/api/events/read-events/index.md) and [Free/Busy](/developers/api/events/free-busy/index.md) requests. This scope is equivalent to **read_events** and **read_free_busy** scopes.
- **write_only** to allow [Create Calendar](/developers/api/calendars/create-calendar/index.md), [Create or Update Events](/developers/api/events/upsert-event/index.md) and [Delete Event](/developers/api/events/delete-event/index.md) 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](/developers/api/events/free-busy/index.md) 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](/developers/api/calendars/create-calendar/index.md) requests.
- **read_events** to allow [Read Events](/developers/api/events/read-events/index.md) 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](/developers/api/events/read-events/index.md) and [Create Notification Channel](/developers/api/push-notifications/create-channel/index.md) requests.
- **create_event** to allow [Create or Update Event](/developers/api/events/upsert-event/index.md) requests.
- **delete_event** to allow [Delete Event](/developers/api/events/delete-event/index.md) requests.
- **read_free_busy** to allow [Free/Busy](/developers/api/events/free-busy/index.md) 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](/developers/api/events/participation-status/index.md) 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`](/developers/api/data-types/index.md) of named scopes, e.g. `read_events create_event delete_event`.
> **WARNING:** The scopes chosen will impact what users see on the initial Cronofy screens of the OAuth flow, but we still need to ask for full privileges from the calendar provider to support all aspects of the API. Unfortunately, the integration options available to us don't allow for us to reduce the scopes we request from users' calendar accounts.
##### `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](https://www.rfc-editor.org/rfc/rfc7636).
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`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) 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
> **INFO:** [Calendar Access Modes](/developers/authorization/access-modes/index.md) offers Free/Busy access to Google and Office 365 (Graph API) with the `provider_name`s - `google_free_busy` Free/Busy access to Google Calendar events - `ms_graph_free_busy` Free/Busy access to Office 365 Providing one of these `provider_name`s is also contingent on providing the `access_mode` param with the value `free_busy`. Please refer to [this documentation](/developers/authorization/access-modes/index.md) for more information. The Free/Busy Calendar Access Mode is in BETA. please contact us at [support@cronofy.com](mailto:support@cronofy.com) if you would like to try this functionality before it gets fully rolled out on March 3rd.
#### 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](/developers/api/authorization/request-token/index.md).
Will always be 32 character [`String`](/developers/api/data-types/index.md) 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`
---
[Read in HTML](/developers/api/authorization/request-authorization/)