Refresh an Access Token

Description #

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": "organizational_unit_scheduler"
}

Request parameters #

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.