Refreshing the Access Token

As the Access Token expires after 2 hours, if your integration needs to access the protected resource beyond that point, you’ll need to use the corresponding refresh_token and the token endpoint of the API to request a new access_token.

To do that, you POST to the Hypermedia API’s token endpoint, accessible from the API home page.

"fx:token": {
    "href": "",
    "title": "The OAuth endpoint for obtaining a new access_token using an existing refresh_token. Post www-form-url-encoded data as follows: grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}",
    "type": "application/json"

The following values need to be POSTed to the token endpoint:

  • grant_type - (required) set to refresh_token
  • refresh_token - (required) as returned when you requested the access token for this user or store

The call also needs to be authenticated to the respective OAuth Client. If possible, passing those details as a header using HTTP Basic Authentication is recommended. To create the header value, base64 encode a combination of the client_id and the client_secret, joined with a :, for example in PHP:

$basic_auth_header = base64_encode($client_id . ":" . $client_secret);

You then pass the encoded value as a header with your request like this:

Authorization: Basic Y2xpZW50X045YTVFZ0hqSVE5NWhzZDBzRDI3OlZzejI2dWUzOFFkU0lnSVFTazRyRGg5YkRCbVRRNE5WU3BoQ1JQbUw=

If HTTP Basic Authentication is not possible, you can instead POST the values separately:

  • client_id - (required) as returned when creating your applications OAuth Client
  • client_secret - (required) as returned when creating your applications OAuth Client

If successful, in response your application will receive a new access_token and access_token_expires. The refresh_token will also be present, but will not have changed. The access_token should be securely handled within your application, replacing the existing access_token.

➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Basic Y2xpZW50X045YTVFZ0hqSVE5NWhzZDBzRDI3OlZzejI2dWUzOFFkU0lnSVFTazRyRGg5YkRCbVRRNE5WU3BoQ1JQbUw=" -d "grant_type=refresh_token&refresh_token=812j49yns9HS46HJ4Djdn38s4HujSHB40S08dd33"

    "scope":"store_id_41000 store_full_access"