Applications
An overview of Commerce Layer's OAuth 2.0 application types
To use Commerce Layer API you need to be authorized in the first place. This means you need to get a valid access token. The permissions you're granted authenticating with that token are determined by the type of API client you used to get it. Three different types of applications are currently available in order to get your credentials: sales channel, integration, and webapp. Which one to use depends on your specific use case.
Sales channel applications are used to build any customer touchpoint (e.g. your storefront with a fully-functional shopping cart and checkout flow).
Sales channels grant not confidential (public) API credentials. They can authenticate by providing just a client ID and their permissions are restricted so that they can be safely used client-side and their tokens exposed to the public without any risks. For example, they can access only one order at a time (the one associated with the shopping cart you're about to checkout, identified by a not guessable, unique hashID) and respond with a
401 Unauthorized error if you try to request a list of orders.Sales channels require a market in scope when requesting their access tokens. This way all the API call results are automatically filtered based on the specified scope. In particular:
- 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).
- Only the prices associated with that market's price list are returned.
- The stock availability is calculated by checking only the stock locations associated with that market (e.g. only the stock items associated with that market's stock locations are returned).
Using a sales channel is the most straightforward way to build your customer touchpoint. Anyway, if you want to have complete control over the grants brought to the access tokens, you can always use an integration. Just make sure not to expose the secret on the client, by building a dedicated backend for frontend (BFF), or properly leveraging serverless functions.
Integration applications are used to develop backend integrations with any 3rd-party system.
Integrations provide confidential API credentials. They need a client ID and a client secret to authenticate and can have one of two roles:
- Read-only — to perform
GETrequests on any single resource or list of resources. - Admin — to perform any CRUD (create, retrieve, update, or delete) action on any resource.
Enterprise users can define custom roles for their integration applications, specifying custom permissions on CRUD actions at the single resource level so as to leverage a granular control, tailored to their needs.
Webapp applications are used to develop custom web app or services for your users, extending Commerce Layer backend with any functionality that is not provided out of the box.
Webapps let you execute the OAuth 2.0 authorization code grant flow to get an access token after a user authorizes an app. They don't come with their own roles and permissions, since they get the set of permissions of the authenticated user.
Last modified 9d ago