The API basics

#Permissions

In some connector use cases, you will need to restrict the access to the API. There are two ways to handle this in the API, depending on the wanted result:

Please see below for more details about both permission systems.

Before diving into those sections, here is one key piece of information you need: those permissions are enforced thanks to the API user you use whenever you ask for a token. All the API calls launched with the generated token afterwards will then benefit from the permissions defined by the user group and the user role of this API user.
In other words, you will need to define for your API user:

  • a role, if you want to use the ACLs permissions,
  • and a group if you want to use the EE permissions.

Can't remember how to get this API user? See here to find out how!

#Endpoint access restrictions

Like when using the PIM through the UI, we use ACLs to define which endpoint a connection can or cannot use.

Here are the simple steps to follow to configure those permissions.

  1. Log into your favorite PIM.
  2. Navigate to the System/Roles menu.
  3. Click on the Create role button.
  4. Input a new name for the user role you are creating, ERP connection user role for example.
  5. In the Users tab, select the API user you created earlier.
  6. In the Web API permissions tab, select the permissions you want to give to your API user.

Web API permission tab screenshot

Web API permission tab screenshot

We strongly recommend you to create dedicated user roles for your API users, different from the user roles that you use for your UI users. So go ahead and create one user role for every API connection you will need.

Do not give any UI permissions to your API user roles.

#Overall access

The first ACL Overall Web API access means that if enabled, each user under that role will have access to the Web API.

You will need to give at least this ACL to all the API user roles you created before for them to be able to call the API.

Do not give this permission to your UI user role as it makes no sense to give API access to UI users.

Note that if a role has Overall Web API access, then it means that all the users under that role will be able to make requests on products, product models and published products.
There is no way to only restrict access to products, except if you are using a 2.x Enterprise Edition. In this case, the EE permissions based on user groups are applied to the API for the products and the published products.

#Catalog structure access

You can fine-tune even more this permission by restricting or allowing access to the entities of the catalog structure (categories, families, attributes, attribute options, channels and locales). The table below lists all the ACLs available.

Permission name If enabled, you will be able to
List categories GET on /categories and on /categories/{category_code}
List families GET on /families and on /families/{family_code}
List family variants (2.x only) GET on /families/{family_code}/variants and on /families/{family_code}/variants/{variant_code}
List attributes GET on /attributes and on /attributes/{attribute_code}
List attribute options GET on /attributes/{attribute_code}/options and on /attributes/{attribute_code}/options/{attribute_option_code}
List attribute group (2.x only) GET on /attribute-groups and on /attributes-groups/{attribute_groups_code}
List association types (2.x only) GET on /association-types and on /association-types/{association_type_code}
List channels GET on /channels and on /channels/{channel_code}
List locales GET on /locales and on /locales/{locale_code}
List currencies (2.x only) GET on /currencies and on /currencies/{currency_code}
Create and update categories POST and PATCH on /categories/{category_code}
PATCH on /categories
Create and update families POST and PATCH on /families/{family_code}
PATCH on /families
Create and update family variants (2.x only) POST and PATCH on /families/{family_code}/variants and on /families/{family_code}/variants/{variant_code}
Create and update attributes POST and PATCH on /attributes/{attribute_code}
PATCH on /attributes
Create and update attribute options POST and PATCH on /attributes/{attribute_code}/options/{attribute_option_code}
PATCH on /attributes/{attribute_code}/options
Create and update attribute groups (2.x only) POST and PATCH on /attribute-groups/{attribute_group_code}
PATCH on /attribute-groups
Create and update association types (2.x only) POST and PATCH on /association-types/{association_type_code}
PATCH on /association-types
Create and update channels (2.x only) POST and PATCH on /channels/{channel_code}
PATCH on /channels

#Catalog permissions (EE only)

The Entreprise Edition permissions based on the user groups are also enforced in the API.

Those permissions are really powerful and make it possible to create great workflows around product enrichment with the API. There are 3 ways to benefit from those permissions. They are detailed in the following sections.

Those permissions were introduced in the API starting from the 2.0 version.

All the permissions described here, apply to both product and product model updates.

#Hide a part of your catalog

With these powerful permissions, you can hide a whole part of your product catalog. It is their very first power.

The EE permissions can be based on three different levels:

  • you can hide products that are inside one or several given categories,
  • you can hide the product information of the attributes that are inside one or several given attribute groups,
  • you can hide the translated product information of one or several given locales.

It can be very useful if:

  • you don't want your third party-connector to mess up with this part of the product catalog.
    For example, you have products created in the PIM coming from your ERP and you want them to be created only in your ERP category tree. You can use the EE permissions to hide the other trees from your connector, this way, it will only be able to create products in the ERP tree.
  • you don't want your third-party connector to be aware of this part of the product catalog.
    For example, you are a reseller and you provide an API connection to one of your suppliers for them to push its product data into the PIM. But you don't want them to be able to access or erase any data that does not involve their products. In this case, you can give them restricted access to the category containing his products, and not to the other suppliers' categories. Pretty neat, right?

To enable these powers:

  1. Log into your favorite PIM and navigate to the System/User groups menu.
  2. Click on the Create group button and input a new name for the user group you are creating, ERP connection user group for example. New ERP connection user group
  3. In the Users tab, select the API user you created earlier. API user in the user group
  4. Then, navigate to the Settings/Categories menu, if you want to benefit from permissions on categories, otherwise jump to step 9.
  5. For each category you want to hide from your API calls, enter the Permissions tab.
  6. Remove the group you just created from the Allowed to view products, Allowed to edit products and Allowed to own products inputs. Don't forget to click on the Save button. Permissions for hide mode
  7. Then, navigate to the Settings/Locales menu, if you want to benefit from permissions on locales, otherwise jump to step 10.
  8. For each locale you want to hide from your API calls, enter the Permissions tab.
  9. Remove the group you just created from the Allowed to view information and Allowed to edit information inputs. Don't forget to click on the Save button.
  10. Then, navigate to the Settings/Attribute groups menu.
  11. For each locale you want to hide from your API calls, enter the Permissions tab.
  12. Remove the group you just created from the Allowed to view attributes and Allowed to edit attributes inputs. Don't forget to click on the Save button.

That's it! 🎉

Don't hesitate to test your configuration by calling the GET product endpoint on a product.
If this product is classified only inside the categories you hide, you should receive a 404, meaning that your configuration worked. 🙂
If you hide a locale, you won't be able to receive the values of the given locale. Check the product body of the answer! If you hide a whole attribute group, you won't be able to receive the values of the attributes that are inside this attribute group. Marvelous!

Note you also won't be able to call any PATCH or POST endpoints on the products you hide thanks to categories.

#Read-only mode on your catalog

The same way you can hide a part of your product catalog, you can also only give a view right to your API user, disabling the right to update products.

This can be pretty useful whenever you only want to share your catalog in a read-only mode. 😉

To enable this possibility:

  1. Log into your favorite PIM.
  2. Navigate to the System/User groups menu.
  3. Click on the Create group button.
  4. Input a new name for the user group you are creating, ERP connection user group for example. New ERP connection user group
  5. In the Users tab, select the API user you created earlier. API user in the user group
  6. Then, navigate to the Settings/Categories menu.
  7. For each category you wish to put in read-only mode, enter the Permissions tab.
  8. Add the group you just created into the Allowed to view products input.
  9. If your user group is already set into the Allowed to own products and Allowed to edit products inputs, remove it. Permissions for read-only mode
  10. Don't forget to click on the Save button.

That's it! 🎉

Don't hesitate to test your configuration by calling the PATCH product endpoint with an update in the body of your product. You should receive a 403, saying that you don't have the right update for this product, exactly the expected behavior!

#Proposals of product information updates

The second power of these permissions is that for some given categories, you can define that the PATCH API endpoints will only be able to suggest modifications on your product values, instead of automatically updating them.
Your PIM users will then be able to validate or reject them directly in the PIM UI. This is perfect if you want to easily control the product information that is pushed into your product catalog. 😉

To enable this possibility:

  1. Log into your favorite PIM.
  2. Navigate to the System/User groups menu.
  3. Click on the Create group button.
  4. Input a new name for the user group you are creating, ERP connection user group for example. New ERP connection user group
  5. In the Users tab, select the API user you created earlier. API user in the user group
  6. Then, navigate to the Settings/Categories menu.
  7. For each category you wish to only create proposals, enter the Permissions tab.
  8. Add the group you just created into the Allowed to view products and Allowed to edit products inputs.
  9. If your user group is already set into the Allowed to own products input, remove it. Permissions for proposals
  10. Don't forget to click on the Save button.

That's it! 🎉

Don't hesitate to test your configuration by calling the PATCH product endpoint with an update in the body of your product. A draft of your product will be created.
You will then need to send your draft for approval by using this API endpoint.
If it works correctly, the owners of the categories where this product is classified will receive a new proposal in their Proposals screen. Below, you can see an example of the generated proposal.

Proposal generated by the API

Proposals can be created only on product updates, not on product creations. 😉

Having trouble creating proposals on one given product?
As soon as your product is at least owned in one category by your API user group, the API will directly apply the updates, instead of creating a draft and then a proposal.
So make sure your product is only classified in categories that are not owned by your API user group.