Request a Service Account 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 #

api.cronofy.com/oauth/token

Example Request #

POST /oauth/token HTTP/1.1
Host: api.cronofy.com
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": 1800,
  "refresh_token": "3gBYG1XamYDUEXUyybbummQWEe5YqPmf",
  "scope": "service_account/accounts/manage",
  "service_account_id": "ser_529716002600402"
}

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 authorization_code.

code required  #

The short-lived, single-use code issued to you when the administrator authorized your access to their Enterprise Connect account as part of an Enterprise Connect Authorization Request.

redirect_uri required  #

The same HTTP or HTTPS URI you passed when requesting the administrator’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 Enterprise Connect account.

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.

service_account_id  #

The ID of the Enterprise Connect account the credentials relate to.

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 administrator’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 administrator to authorize access again so that you can be issued a new code.

Search