Refresh token

How to execute the authorization flow and get your access token

The refresh_token grant type is used by clients to exchange a refresh token for an expired access token.

Sales channels can use this grant type to refresh a customer's access token with a "remember me" option. Webapps can use it to refresh the access token skipping the authorization code step.

If a scope (different from the default market:all) was included in the expired access token request, you must specify the same scope when using the refresh token.

Getting an access token

To get an access token using the refresh_token grant type, send a POST request to the /oauth/token endpoint, passing the API client credentials in the request body.

Request

POST https://auth.commercelayer.io/oauth/token

Arguments

Body parameter	Type	Required	Description
grant_type	String	Required	refresh_token
refresh_token	String	Required	A valid refresh_token.
client_id	String	Required	Your application's client ID.
client_secret	String	Optional	Your application's client secret (required for confidential API credentials — i.e. in case of authorization code flow).
scope	String	Optional	Your access token scope (market, stock location). Required if the expired access token had a scope (must be the same).

Examples

Sales channel with password flow

Request

The following request tries to exchange a valid refresh token for an expired access token:

curl -g -X POST \
  'https://auth.commercelayer.io/oauth/token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "{{your_refresh_token}}",
    "client_id": "{{your_client_id}}",
    "scope": "market:id:xYZkjABcde"
  }'

Response

On success, the API responds with a 200 OK status code, returning the requested access token and customer info:

{
    "access_token": "acC3sSt0K3Nwrt6kic7.abc4bnm5...",
    "token_type": "bearer",
    "expires_in": 14400,
    "refresh_token": "r3fResHt0k3ndfg6eft3gbj167",
    "scope": "market:id:xYZkjABcde",
    "created_at": 123456789,
    "owner_id": "zxcVBnMASd",
    "owner_type": "customer"
}

Webapp with authorization code flow

Request

The following request tries to exchange a valid refresh token for an expired access token:

curl -g -X POST \
  'https://auth.commercelayer.io/oauth/token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "grant_type": "refresh_token",
  "refresh_token": "{{your_refresh_token}}",
  "client_id": "{{your_client_id}}",
  "client_secret": "{{your_client_secret}}"
}'

Response

On success, the API responds with a 200 OK status code, returning the requested access token and customer info:

{
    "access_token": "acC3sSt0K3Nwrt6kic7.abc4bnm5...",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "r3fResHt0k3ndfg6eft3gbj167",
    "scope": "market:all",
    "created_at": 123456789,
    "owner_id": "zxcVBnMASd",
    "owner_type": "user"
}