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 #

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/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"
  }
}

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.

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.

redirect_uri required #

The same HTTP or HTTPS URI you passed when requesting the user’s authorization.

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 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 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 with a fixed length of 28 characters.

sub #

This specifies the internal Cronofy ID for the account the credentials relate to, ASCII-only String 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.

Currently one of:

apple
cronofy
exchange
google
live_connect

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.

Currently one of:

cronofy
exchange
google
gsuite
icloud
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.

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.

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/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/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_grant"
}

If the redirect_uris are identical this error can only be resolved by requesting the user to authorize access again so that you can be issued a new code.