The list of resources that we can access depends on our user type and is defined within our module webapi.xml configuration file.

There are three types of users known to API, listed as follows:

Two files play a crucial role toward defining an API: our module acl.xml and webapi.xml files.

acl.xml is where we define our module access control list (ACL). It defines an available set of permissions to access the resources. The acl.xml files across all Magento modules are consolidated to build an ACL tree that is used to select allowed admin role resources or third-party integration's access (System | Extensions | Integrations | Add New Integration | Available APIs).

webapi.xml is where we define Web API resources and their permissions. When we create webapi.xml, the permissions defined in acl.xml are referenced to create access rights for each API resource.

Let's take a look at the following (truncated) webapi.xml from the core Magento_Cms module:

<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation= "urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    ...
    <route url="/V1/cmsPage" method="POST">
        <service class="MagentoCmsApiPageRepositoryInterface" method="save" />
        <resources>
            <resource ref="Magento_Cms::page" />
        </resources>
    </route>
    ...
    <route url="/V1/cmsBlock/search" method="GET">
        <service class="MagentoCmsApiBlockRepositoryInterface" method="getList" />
        <resources>
            <resource ref="Magento_Cms::block" />
        </resources>
    </route>
    ...
</routes>

In the preceding webapi.xml file for the CMS page API, only a user with Magento_Cms::page authorization can access POST /V1/cmsPage or GET /V1/cmsBlock/search. We will get back to a more detailed explanation of route later on in our examples; for the moment, our focus is on resource. We can assign multiple child resource elements under resources. In cases like these, it would be sufficient for a user to have any one of those ACLs assigned to be able to make an API call.

The actual authorization is then granted to either an administrator or integration, defined in the Magento admin, with full group or a specific resource selected in the ACL tree as shown in the following screenshot:

Given that webapi.xml and acl.xml go hand in hand, let's take a look at the (truncated) acl.xml file from the core Magento_Cms module:

<resources>
    <resource id="Magento_Backend::admin">
        <resource id="Magento_Backend::content">
            <resource id="Magento_Backend::content_elements">
                <resource id="Magento_Cms::page" ...>
                    ...
                </resource>
            </resource>
        </resource>
    </resource>
</resources>

Notice how the position of the Magento_Cms::page resource is nested under Magento_Backend::content_elements, which in turn is nested under Magento_Backend::content, which is further nested under Magento_Backend::admin. This tells Magento where to render the ACL under Magento admin when showing the Roles Resources tree as shown in the previous screenshot. This does not mean that the user authorized against the Magento_Cms::page resource won't be able to access the API if all those parent Magento_Backend resources are granted to him as well.

Authorizing against a resource is sort of a flat thing. There is no tree check when authorizing. Thus, each resource is required to have a unique id attribute value on a resource element when defined under acl.xml.

The resources just defined are what we listed before as resources for which administrators or integrators are authorized.

The customer, on the other hand, is assigned a resource named anonymous or self. If we were to do a full <resource ref="anonymous" /> string search across all Magento core modules, several occurrences would show up.

Let's take a look at the (truncated) core module vendor/magento/module-catalog/etc/webapi.xml file:

<route url="/V1/products" method="GET">
    <service class= "MagentoCatalogApiProductRepositoryInterface" method="getList"/>
    <resources>
        <resource ref="anonymous" />
    </resources>
</route>

The preceding XML defines an API endpoint path with a value of /V1/products, available via the HTTP GET method. It further defines a resource called anonymous, which means either the currently logged-in customer or guest user can call this API endpoint.

anonymous is a special permission that doesn't need to be defined in acl.xml. As such, it will not show up in the permissions tree under Magento admin. This simply means that the current resource in webapi.xml can be accessed without the need for authentication.

Finally, we take a look at the self resource, whose example we can find under the (truncated) vendor/magento/module-customer/etc/webapi.xml file as follows:

<route url="/V1/customers/me" method="PUT">
    <service class= "MagentoCustomerApiCustomerRepositoryInterface" method="save"/>
    <resources>
        <resource ref="self"/>
    </resources>
    <data>
        <parameter name="customer.id" force="true">%customer_id%</parameter>
    </data>
</route>

self is a special kind of access that enables a user to access resources they own, assuming we already have an authenticated session with the system. For example, GET /V1/customers/me fetches the logged-in customer's details. This is something that is typically useful for JavaScript-based components/widgets.