Roles and permissions

How to set specific permitted actions for each resource

Commerce Layer supports a granular access control system on a resource level. Each access token gets a specific set of permissions. The client and the authorization flow determine your permitted actions for each resource.

Authentication

Sales channel

Sales channels support client_credentials, password and refresh_token grant types. Given their limited permissions, they can be safely used in client-side applications.

Client credentials

Sales channels that authenticate through client_credentials get the following permissions.

For security reasons sales channels can read resource lists only for a subset of resources (e.g. SKUs, prices, bundles, etc. — Show+List in the table below). Getting a list is not allowed for all the other resources (only Show in the table below). For example, a sales channel is authorized to perform a GET request to the /api/orders/xYZkjABcde but not to the /api/orders endpoint.

Resource	Create	Read	Update	Delete	Restrictions
Addresses		Show			Single resource only.
Application		Show			The kind of API credentials you're currently using.
Bundles		ListShow			Bundles associated with the market in scope, or (if no market is in scope) with the currency code of the price list in scope.
Customers
Customer subscriptions		Show			Single resource only.
Delivery lead times		ListShow			Delivery lead times associated with the shipping methods accessible by scope.
Geocoders		Show			Single resource only.
Gift cards		Show			If draft (single resource only).
Gift card recipients		Show			Single resource only.
In-stock subscriptions		Show			In-stock subscriptions associated with the market in scope (single resource only).
Line items		Show			Can be read if belonging to draft, pending or placed orders and updated/deleted if belonging to draft or pending orders (single resource only).
Line item options		Show			Can be read if belonging line items associated with draft, pending or placed orders and updated/deleted if belonging to line items associated with draft or pending orders (single resource only).
Notifications		ListShow
Orders		Show			Can be read if draft, pending or placed and updated if draft or pending (single resource only).
Organization		Show			Your current organization.
Payment methods		ListShow			Enabled payment methods associated with the market in scope, or (if no market is in scope) with the currency code of the price list in scope.
Payment sources		Show			Can be read if belonging to draft, pending or placed orders and updated/deleted if belonging to draft or pending orders (single resource only).
Prices		ListShow			Prices associated with the market price list.
Price tiers		ListShow			Price tiers associated with the prices accessible by scope.
Promotions		ListShow			Active promotions associated with the market in scope, or (if no market is in scope) with the currency code of the price list in scope.
Promotion rules		Show			Promotion rules associated with the promotions accessible by scope (single resource only).
Reserved stocks		ListShow			Reserved stocks belonging to the stock items of the stock locations associated with the market in scope.
Shipments		Show			Can be read if belonging to draft, pending or placed orders and updated if belonging to draft or pending orders (single resource only).
Stock line items		Show			Can be read if belonging to shipments associated with draft, pending, editing or placed orders (single resource only).
Shipping methods		ListShow			Enabled shipping methods associated with the market in scope, or (if no market is in scope) with the currency code of the price list in scope. If stock location is specified, it's matched with the one in scope.
Shipping method tiers		ListShow			Shipping method tiers associated with the shipping methods accessible by scope.
SKUs		ListShow			SKUs with stock items in the market inventory model (unless not tracked), a price in the market price list (unless external prices allowed).
SKU options		ListShow			SKU options associated with the market in scope, or (if no market is in scope) with the currency code of the price list in scope.
SKU lists		Show			Single resource only.
SKU list items		Show			Single resource only.
Stock items		ListShow			SKU items belonging to the stock locations associated with the market in scope.
Stock transfers		Show			Can be read if belonging to shipments associated with draft, pending, editing or placed orders (single resource only).
Subscription models		ListShow			Subscription models associated with the market in scope.

Password

Sales channels can authenticate a customer through the password flow. The access tokens that they get include the sum of the client credentials permissions plus the ones below.

Resource	Create	Read	Update	Delete	Restrictions
Customers					The customer must be the authenticated resource owner.
Customer addresses					The customer must be the authenticated resource owner.
Customer payment sources					The customer must be the authenticated resource owner.
Customer subscriptions					The customer must be the authenticated resource owner.
Line items					The line items must belong to one of the customer's orders.
Line item options					The line item options must belong to one of the line items associated with one of the customer's orders.
Orders					Can be deleted only if in editing status. The customer must be the authenticated resource owner.
Order subscriptions					The subscriptions must be associated with one of the customer's orders.
Order subscription items					The subscriptions items must be associated with one of the customer's subscriptions.
Parcels					The parcels must belong to one of the customer's orders.
Parcel line items					The parcel line items must belong to one of the parcels associated with one of the customer's orders.
Returns					Can be created for one of the customer's order and updated if in draft status.
Return line items					The return line items must belong to one of the returns associated with one of customer's order.
Shipments					The shipments must belong to one of the customer's orders.
SKU lists					The customer must be the authenticated resource owner.
SKU list items					The customer must be the authenticated owner of the associated SKU list.

Since customer tokens extend sales channels abilities, to get a list of resources belonging to a customer for those resources that sales channels cannot list you need to fetch them as relationships via the api/customers endpoint. For example, you can get all the orders belonging to a customer by querying with a customer token the endpoint api/customers/xYZkjABcde/orders, where xYZkjABcde is the ID of the customer for which the token was issued.

Refresh token

An access token obtained through a refresh_token inherit the same set of permissions as the one that expired.

Integration

Integrations support the client_credentials grant type. The access tokens that they get include the set of permissions of their role.

With very few exceptions, the Core resources not listed in one of the tables above are likely manageable using integration API credentials only.

Webapp

Webapps support authorization_code and refresh_token grant types. They don't bring any grants to the access tokens and get the set of permissions of the authenticated user's role. Access tokens obtained through a refresh_token inherit the same set of permissions as the one that expired.