Authentication
How to get your access token, based on OAuth 2.0 grants
All API requests must be authenticated. To get authorized, you must include a valid access token in the Authorization header:
Authorization: Bearer your-access-token
To get a valid access token you need to send a
POST request to the /oauth/token endpoint. The payload to be sent with the request differs based on the kind of application you're requesting the access token for and will be detailed case by case in the following sections.Please note that the
/oauth/token endpoint is subject to a rate limit of max 20 reqs / 1 min both in live and test mode.To get an access token, you need to execute an authorization flow by using valid API credentials for the client.
Grant type | Sales channel | Integration | Webapp |
|---|---|---|---|
Client credentials | |||
Password | |||
Authorization code | |||
Refresh token |
For security reasons, access tokens expire after a default period of time. Your access token lifetime differs based on the kind of application you're using:
API client | Default lifetime |
|---|---|
4 hours | |
2 hours | |
2 hours |
You can specify a custom lifetime for the token at the application level on the admin dashboard when you create/update each of them. The token lifetime value must be expressed in seconds and fall within a min of 2 hours (7200 secs) and a max of 1 year (31536000 secs).
To avoid security issues, be careful not to set too long expiration dates for your access tokens (especially the sales channel ones, usually used client-side) because they cannot be revoked (i.e. even if you request a new one, the old one will stay valid until its original expiration date).
For each of the above authorization flows you can restrict the scope to a specific active market and/or stock location.
The access token scope is a string composed by
"{{resource_name}}:{{resource_number}}", where resource_number is the number — not the ID — of the market or stock location you want to put in scope.By including a market scope in the access token request —
market:1234 — all the resources (e.g. SKUs, prices, stock items) that you fetch are automatically filtered.{
"grant_type": "authorization-grant",
"client_id": "your-client-id",
...,
"scope": "market:1234"
}
The market in scope must be active (e.g. enabled). Disabled markets are excluded from any authorization scope recalculation.
When fetching a collection of SKUs with a market in scope only the SKUs that are sellable in that market are returned. To be sellable in a market an SKU must have a price in the market's price list and at least one stock item in one of the market's stock locations, regardless of its quantity.
Sales channels require a market in scope when requesting their access tokens to perform the permitted CRUD actions. If the market in scope is associated with a customer group, it becomes private and can be accessed only by the customers belonging to the group — in that case, to get your token you must use the password flow.
By including a stock location scope in the access token request —
stock_location:4567 — the stock is restricted to the SKUs available in that specific stock location.{
"grant_type": "authorization-grant",
"client_id": "your-client-id",
...,
"scope": "market:1234 stock_location:4567"
}
When putting a stock location in scope, adding the associated market in the access token request is mandatory. If the market scope is missing or the stock location doesn't belong to the market in scope the API responds with a
400 Bad Request error code.Last modified 4mo ago