Refresh an Access Token
Required plan: StarterDescription #
Access Tokens are refreshed as specified in section 6 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
Host: {data_center_url}
Content-Type: application/json; charset=utf-8
{
"client_id": "{CLIENT_ID}",
"client_secret": "{CLIENT_SECRET}",
"grant_type": "refresh_token",
"refresh_token": "{REFRESH_TOKEN}"
}
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": "{REFRESH_TOKEN}",
"scope": "create_event delete_event"
}
Request parameters #
data_center_url required
The URL for the data center you want to communicate with. Possible choices are:
api-au.cronofy.com
- 🇦🇺 Australiaapi-ca.cronofy.com
- 🇨🇦 Canadaapi-de.cronofy.com
- 🇩🇪 Germanyapi-sg.cronofy.com
- 🇸🇬 Singaporeapi-uk.cronofy.com
- 🇬🇧 United Kingdomapi.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 refresh_token
.
refresh_token required #
The refresh_token
issued to you when the user authorized your access to their account.
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. Note that this can differ to the one you provided as the refresh_token
will be rotated periodically to improve security. Therefore, if the refresh_token
in the response differs to the one sent by you in the request, you MUST store the new refresh_token
as the old one will no longer be valid.
Failure to store the new refresh_token
will mean that the user will have to reauthorize your access once the Access Token expires as you will no longer have a valid refresh_token
to request a new one.
Will always be a 32 character String
of ASCII characters.
scope #
The Access Token Scope as defined in section 3.3 of RFC 6749.
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 refresh_token
is unrecognized or revoked.
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
"error": "invalid_grant"
}
This error can only be resolved by requesting the user to authorize access again so that you can be issued a new code
and then request a new set of Access and Refresh Tokens.