# Request an Access Token #### Description Access Tokens are issued as specified in section 4.1.3 of RFC 6749, authentication is performed by including your `client_id` and `client_secret`, as issued by Cronofy, within the body of the request. As with the rest of the API, all requests can be made with a JSON- or forms-encoded request body, though a JSON-encoded request is recommended. You should specify the `Content-Type` header of your requests as either `application/json; charset=utf-8` or `application/x-www-form-urlencoded` to signal your request body is JSON- or forms-encoded, respectively. #### URL format ``` {data_center_url}/oauth/token ``` #### Example Request ```http POST /oauth/token HTTP/1.1 Content-Type: application/json; charset=utf-8 { "client_id": "{CLIENT_ID}", "client_secret": "{CLIENT_SECRET}", "grant_type": "authorization_code", "code": "{CODE}", "redirect_uri": "{REDIRECT_URI}" } ``` #### Example Response ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Cache-Control: no-store Pragma: no-cache { "token_type": "bearer", "access_token": "P531x88i05Ld2yXHIQ7WjiEyqlmOHsgI", "expires_in": 3600, "refresh_token": "3gBYG1XamYDUEXUyybbummQWEe5YqPmf", "scope": "create_event delete_event", "account_id": "acc_5ba21743f408617d1269ea1e", "sub": "acc_5ba21743f408617d1269ea1e", "linking_profile": { "provider_name": "google", "profile_id": "pro_n23kjnwrw2", "profile_name": "example@cronofy.com" }, "userinfo": { "sub": "acc_5700a00eb0ccd07000000000", "email": "janed@company.com", "name": "Jane Doe", "cronofy.data": { "authorization": { "scope": "read_write", "status": "active" }, "profiles": [ { "provider_name": "google", "provider_service": "gsuite", "profile_id": "pro_n23kjnwrw2", "profile_name": "example1@cronofy.com", "profile_connected": true, "profile_initial_sync_required": true, "profile_calendars": [ { "calendar_id": "cal_n23kjnwrw2_jsdfjksn234", "calendar_name": "Home", "calendar_readonly": false, "calendar_deleted": false, "calendar_primary": true, "calendar_integrated_conferencing_available": true, "calendar_attachments_available": false, "permission_level": "sandbox" } ] } ] } } } ``` #### Request parameters ##### `data_center_url` *(required)* The URL for the data center you want to communicate with. Possible choices are: - `api-au.cronofy.com` - Australia - `api-ca.cronofy.com` - Canada - `api-de.cronofy.com` - Germany - `api-sg.cronofy.com` - Singapore - `api-uk.cronofy.com` - United Kingdom - `api.cronofy.com` - United States Find out more about [Cronofy's data centers](/developers/data-centers/index.md). ##### `client_id` *(required)* The `client_id` issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your `client_secret`. ##### `client_secret` *(required)* The `client_secret` issued to you by Cronofy to authenticate your OAuth Client. Authenticates you as a trusted client along with your `client_id`. ##### `grant_type` *(required)* Must always be `authorization_code`. ##### `code` *(required)* The short-lived, single-use `code` issued to you when the user authorized your access to their account as part of an [Authorization Request](/developers/api/authorization/request-authorization/index.md). ##### `redirect_uri` *(required)* The same HTTP or HTTPS URI you passed when requesting the user's authorization. ##### `code_verifier` *(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). If a `code_challenge` parameter was provided as part of the [Request Authorization](/developers/api/authorization/request-authorization/index.md) then this parameter is required. #### Response parameters ##### `token_type` Describes the type of the token as defined in section 7.1 of RFC 6749. Will always be `bearer`. ##### `access_token` The new Access Token to use to authenticate when using the API on behalf of the user. Will always be a 32 character [`String`](/developers/api/data-types/index.md) of ASCII characters. ##### `expires_in` An approximate number of seconds that the new Access Token will be valid for. Will always be a positive integer no greater than 2,147,483,647. This value may be used to pre-emptively request a new Access Token when this one is expected to have already expired. However, as being issued new Access Tokens counts for rate limiting but a `401 Unauthorized` response for an invalid Access Token does not, it is recommended to use each Access Token you received for as long as possible. ##### `refresh_token` The `refresh_token` for the granted authorization. Will always be a 32 character [`String`](/developers/api/data-types/index.md) of ASCII characters. ##### `scope` The Access Token Scope as defined in section 3.3 of RFC 6749. ##### `account_id` This specifies the internal Cronofy ID for the account the credentials relate to, ASCII-only [`String`](/developers/api/data-types/index.md) with a fixed length of 28 characters. ##### `sub` This specifies the internal Cronofy ID for the account the credentials relate to, ASCII-only [`String`](/developers/api/data-types/index.md) with a fixed length of 28 characters. ##### `linking_profile` The details of the profile used to authorize access as part of the authorization flow that generated the `code`. Will not necessarily be returned as not all authorization flows are guaranteed to involve a profile. ##### `linking_profile.provider_name` This specifies the provider of the calendar as a lowercase, ASCII-only [`String`](/developers/api/data-types/index.md). Currently one of: - `apple` - `cronofy` - `exchange` - `google` - `google_free_busy` - `live_connect` - `ms_graph_free_busy` However, this will be expanded over time and therefore consumers should support any value for this field. ##### `linking_profile.provider_service` This specifies the service that hosts the calendar as a lowercase, ASCII-only [`String`](/developers/api/data-types/index.md). Currently one of: - `cronofy` - `exchange` - `google` - `google_free_busy` - `gsuite` - `icloud` - `ms_graph_free_busy` - `office365` - `outlook_com` However, this will be expanded over time and therefore consumers should support any value for this field. This should be used to help a user distinguish between their profiles as they can have multiple profiles with the same name. ##### `linking_profile.profile_id` This specifies the ID of the profile, a profile may consist of many calendars, as an ASCII-only [`String`](/developers/api/data-types/index.md). This is used for targeting other API actions toward this profile. ##### `linking_profile.profile_name` This specifies the name of the profile as a [`String`](/developers/api/data-types/index.md). ##### `userinfo` Returns identifying information for the authenticated account. You can see more about the UserInfo response parameters in [UserInfo documentation](/developers/api/identity/userinfo/index.md). #### Error responses ##### 400 Bad Request Follows the format specified in section 5.2 of RFC 6749, common examples are provided for reference. ###### Invalid Client Signifies an unrecognized combination of `client_id` and `client_secret`. ```http HTTP/1.1 400 Bad Request Content-Type: application/json; charset=utf-8 { "error": "invalid_client" } ``` This error can be resolved by ensuring your `client_id` and `client_secret` are set correctly. Alternatively, you may ask Cronofy to issue you new client credentials but be aware that this will revoke all existing Access and Refresh Tokens. ###### Invalid Grant Signifies that the `code` is unrecognized or has already been used, or that the `redirect_uri` does not match the one given when requesting the user's authorization. ```http HTTP/1.1 400 Bad Request Content-Type: application/json; charset=utf-8 { "error": "invalid_grant" } ``` If the `redirect_uri`s are identical this error can only be resolved by requesting the user to [authorize access again](/developers/api/authorization/request-authorization/index.md) so that you can be issued a new `code`. --- [Read in HTML](/developers/api/authorization/request-token/)