Authentication

All API requests must be authenticated. To get authorized, you must include a valid access token in the Authorization header:

Authorization: Bearer {{access_token}}

To get an access token, you need to execute an authorization flow by using a valid application as the client. The authorization flow depends on the grant type as described in the table below:

Client Credentials Password Authorization Code Refresh Token
Channel
Integration
Zapier
Webapp
Note: For security reasons, access tokens expire after 2 hours. Refresh tokens expire after 2 weeks.

Client Credentials

Channel applications use the Client Credentials grant type to get a "guest" access token. Integration applications use the Client Credentials grant type to get an access token for themselves. By including a market scope in the access token request, all the resources (e.g., SKUs, prices, stock items) that you fetch are automatically filtered.

Example request
POST /oauth/token
Request body
{
  "grant_type": "client_credentials",
  "client_id": "{{client_id}}",
  "client_secret": "{{client_secret}}",
  "scope": "{{scope}}"
}
Parameters
client_id
required
Your application's client_id
Example:
6a38ccf37a944d7d1bf7ddea4d231f3bf5c7534fd5d7c3f43252e6c53e40d6cc
client_secret
optional
Your application's client_secret, not used by public channel applications
Example:
d47681850ffcaa01435868adfaad6755e6d11cb0e3043133db12ab743205f960
scope
optional
Your access token scope, which is a string composed by "market:" + market_id
Example:
market:1234
Example response
{
  "token_type": "bearer",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJvcmdhbml6YXRpb24iOnsiaWQiOjQwfSwiYXBwbGljYXRpb24iOnsiaWQiOjQwLCJraW5kIjoiaW50ZWdyYXRpb24iLCJwdWJsaWMiOmZhbHNlfSwidGVzdCI6dHJ1ZSwiZXhwIjoxNTMxMTYzODMyfQ.q-e9ohnNgFiKYvseVncuD2vm7eqO2--0BzxVLROsq3se_Z6xtgPH6pv5DWb9ED9rLht_tVBzA7bcZJUS9PUFfA",
  "scope": "market:1234",
  "refresh_token": nil,
  "created_at": 1531156632,
  "expires_in": 1531163832
}

Password

The Password grant type is used by channel applications to exchange a customer's credentials for an access token, i.e., to get a "logged" access token.

Example request
POST /oauth/token
Request body
{
  "grant_type": "password",
  "username": "{{customer_email}}",
  "password": "{{customer_password}}",
  "client_id": "{{client_id}}",
  "client_secret": "{{client_secret}}",
  "scope": "{{scope}}"
}
Parameters
customer_email
required
The customer's email address
customer_password
required
The customer's password
Example:
secret
client_id
required
Your application's client_id
Example:
6a38ccf37a944d7d1bf7ddea4d231f3bf5c7534fd5d7c3f43252e6c53e40d6cc
client_secret
optional
Your application's client_secret
Example:
d47681850ffcaa01435868adfaad6755e6d11cb0e3043133db12ab743205f960
scope
optional
Your access token scope (market)
Example:
market:1234
Example response
{
  "token_type": "bearer",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJvcmdhbml6YXRpb24iOnsiaWQiOjQwfSwiYXBwbGljYXRpb24iOnsiaWQiOjQwLCJraW5kIjoiaW50ZWdyYXRpb24iLCJwdWJsaWMiOmZhbHNlfSwidGVzdCI6dHJ1ZSwiZXhwIjoxNTMxMTYzODMyfQ.q-e9ohnNgFiKYvseVncuD2vm7eqO2--0BzxVLROsq3se_Z6xtgPH6pv5DWb9ED9rLht_tVBzA7bcZJUS9PUFfA",
  "scope": "market:1234",
  "refresh_token": "6426f54e7b3f1713e641ba51ab93b0f18a5aa1cf002bb0db5df82219775e2707",
  "owner_type": "customer",
  "owner_id": 1234,
  "created_at": 1531156632,
  "expires_in": 1531163832
}

Refresh Token

The Refresh Token grant type is used by clients to exchange a refresh token for an expired access token. Channel applications can use the Refresh Token grant type to refresh a customer's access token with a "remember me" option.

Example request
POST /oauth/token
Request body
{
"grant_type": "refresh_token",
"refresh_token": "{{refresh_token}}",
"client_id": "{{client_id}}",
"client_secret": "{{client_secret}}"
}
Parameters
refresh_token
required
A valid refresh_token
Example:
c0eac0f4b2c051a1696d08b32d3f9b4de36828db3a3c5a5cabd0e8241b34a422
client_id
required
Your application's client_id
Example:
6a38ccf37a944d7d1bf7ddea4d231f3bf5c7534fd5d7c3f43252e6c53e40d6cc
client_secret
optional
Your application's client_secret
Example:
d47681850ffcaa01435868adfaad6755e6d11cb0e3043133db12ab743205f960
Example response
{
  "token_type": "bearer",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJvcmdhbml6YXRpb24iOnsiaWQiOjM4fSwiYXBwbGljYXRpb24iOnsiaWQiOjM4LCJraW5kIjoid2ViYXBwIiwicHVibGljIjpmYWxzZX0sInRlc3QiOnRydWUsIm93bmVyIjp7ImlkIjoxOCwidHlwZSI6IkN1c3RvbWVyIn0sImV4cCI6MTUzMTE2NDIyNn0.5dgbD8lPwuHTtVfBN4Mh3ifS8KQd9-TPAahUfLEigmV3_XeiMV3nBViv-8Ob6cbxwhwTmmN3ursvArrZbja2zw",
  "scope": "market:1234",
  "refresh_token": "95342a5d8d4e47b28dca8a3cbff1791b620baa344e514eafc3b87c0ce9d5f1ac",
  "owner_type": "customer",
  "owner_id": 1234,
  "created_at": 1531157026,
  "expires_in": 1531164226
}

Authorization Code

The Authorization Code grant type is used by webapp applications to exchange an authorization code for an access token. Unlike the other grant types, the Authorization Code flow requires two steps:

  1. Get an authorization code
  2. Exchange the authorization code with an access token

Step 1 of 2 - Get an authorization code
GET /oauth/authorize?client_id={{client_id}}&redirect_uri={{redirect_uri}}&scope={{scope}}&response_type=code
Parameters
client_id
required
Your application's client_id
Example:
6a38ccf37a944d7d1bf7ddea4d231f3bf5c7534fd5d7c3f43252e6c53e40d6cc
redirect_uri
required
Your application's redirect uri
Example:
https://yourdomain.com/oauth/redirect
scope
optional
Your access token scope (market)
Example:
market:1234
If the client_id exists, the user is prompted to authorize the 3rd party application to access their data. After the authorization, the browser is redirected to the redirect_uri with a code parameter in the URL.
Step 2 of 2 - Get an access token
POST /oauth/token
Request body
{
  "grant_type": "authorization_code",
  "code": "{{authorization_code}}",
  "client_id": "{{client_id}}",
  "client_secret": "{{client_secret}}",
  "redirect_uri": "{{redirect_uri}}",
  "scope": "{{scope}}"
}
Parameters
code
required
The authorization code that you got from the redirect_uri query string
Example:
8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1
client_id
required
Your application's client_id
Example:
6a38ccf37a944d7d1bf7ddea4d231f3bf5c7534fd5d7c3f43252e6c53e40d6cc
client_secret
required
Your application's client_secret
Example:
d47681850ffcaa01435868adfaad6755e6d11cb0e3043133db12ab743205f960
redirect_uri
required
Your application's redirect uri
Example:
https://yourdomain.com/oauth/redirect
scope
optional
Your access token scope (market)
Example:
market:1234
Example response
{
  "token_type": "bearer",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJvcmdhbml6YXRpb24iOnsiaWQiOjQwfSwiYXBwbGljYXRpb24iOnsiaWQiOjQwLCJraW5kIjoiaW50ZWdyYXRpb24iLCJwdWJsaWMiOmZhbHNlfSwidGVzdCI6dHJ1ZSwiZXhwIjoxNTMxMTYzODMyfQ.q-e9ohnNgFiKYvseVncuD2vm7eqO2--0BzxVLROsq3se_Z6xtgPH6pv5DWb9ED9rLht_tVBzA7bcZJUS9PUFfA",
  "scope": "market:1234",
  "refresh_token": "6426f54e7b3f1713e641ba51ab93b0f18a5aa1cf002bb0db5df82219775e2707",
  "owner_type": "user",
  "owner_id": 1234,
  "created_at": 1531156632,
  "expires_in": 1531163832
}

Get our machine-readable JSON schema that follows the OpenAPI Specification (formerly Swagger).

Get our Postman collection in one click and start making real calls to Commerce Layer API in minutes.

Get in touch with our support team if you have any questions or want to learn more about Commerce Layer.