Web API authentication overview
Magento allows developers to define web API resources and their permissions in a configuration file webapi.xml
.
Here are more details on exposing services as Web APIs.
Before you can make web API calls, you must authenticate your identity and have necessary permissions (authorization) to access the API resource. Authentication allows Magento to identify the caller's user type. Based on the user's (administrator, integration, customer or guest) access rights, API calls' resource accessibility is determined.
Accessible resources
The list of resources that you can access depends on your user type. All customers have the same permissions, and as a result the same resources accessible. The preceding statement is true for guest users as well.
Each administrator or integration user can have a unique set of permissions which is configured in the Magento Admin.
Permissions required to access particular resource are configured in the webapi.xml
file. This table lists the resources that each user type can access:
User type | Accessible resources (defined in webapi.xml ) |
---|---|
Administrator or Integration |
Resources for which administrators or integrators are authorized. For example, if administrators are authorized for the |
Customer |
Resources with |
Guest user |
Resources with |
Relation between acl.xml and webapi.xml
The acl.xml
file defines the access control list (ACL) for a given module. It defines available set of permissions to access the resources.
acl.xml
files across all Magento modules are consolidated to build an ACL tree which is used to select allowed Admin role resources or third party Integration's access (System > Extension > Integration > Add New Integration > Available APIs).
Sample customer acl.xml
For example, account management, customer configuration, and customer group resource permissions are defined in the Customer module鈥檚 acl.xml
.
When a developer creates the Web API configuration file (webapi.xml
), the permissions defined in acl.xml are referenced to create access rights for each API resource.
Sample (truncated) customer webapi.xml
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
<!-- Customer Group -->
<route url="/V1/customerGroups/:id" method="GET">
<service class="Magento\Customer\Api\GroupRepositoryInterface" method="getById"/>
<resources>
<resource ref="Magento_Customer::group"/>
</resources>
</route>
............
.......
.....
<!-- Customer Account -->
<route url="/V1/customers/:customerId" method="GET">
<service class="Magento\Customer\Api\CustomerRepositoryInterface" method="getById"/>
<resources>
<resource ref="Magento_Customer::customer"/>
</resources>
</route>
<route url="/V1/customers" method="POST">
<service class="Magento\Customer\Api\AccountManagementInterface" method="createAccount"/>
<resources>
<resource ref="anonymous"/>
</resources>
</route>
<route url="/V1/customers/:id" method="PUT">
<service class="Magento\Customer\Api\CustomerRepositoryInterface" method="save"/>
<resources>
<resource ref="Magento_Customer::manage"/>
</resources>
</route>
<route url="/V1/customers/me" method="PUT">
<service class="Magento\Customer\Api\CustomerRepositoryInterface" method="save"/>
<resources>
<resource ref="self"/>
</resources>
<data>
<parameter name="customer.id" force="true">%customer_id%</parameter>
</data>
</route>
..........
.....
...
For example, in the preceding webapi.xml
for the customerGroups resource, only a user with Magento_Customer::group
authorization can GET /V1/customerGroups/:id
. On the other hand, you can create a customer using POST /V1/customers
anonymously (or by a guest).
Authorization is granted to either an administrator (or an integration) defined in the Magento Admin with the customer group selected as one of the resources in the ACL tree.
A guest or anonymous is a special permission that doesn't need to be defined in acl.xml
(and will not show up in the permissions tree in the Magento Admin). It just indicates that the current resource in webapi.xml
can be accessed without the need for authentication.
Similarly, self is a special access used if you already have an authenticated session with the system. Self access enables a user to access resources they own. For example, GET /V1/customers/me
fetches the logged-in customer's details. This is typically useful for JavaScript-based widgets.
Web API clients and authentication methods
You use a client, such as a mobile application or an external batch job, to access Magento services using web APIs.
Each type of client has a preferred authentication method. To authenticate, use the authentication method for your preferred client:
Client | Authentication method and process |
---|---|
Mobile application |
Registered users use token-based authentication to make web API calls using a mobile application. The token acts like an electronic key that provides access to the API(s).
|
Third-party application |
Third-party applications use OAuth-based authentication to access the web APIs.
|
JavaScript widget on the Magento storefront or Magento Admin |
Registered users use session-based authentication to log in to the Magento storefront or Magento Admin. A session is identified by a cookie and time out after a period of inactivity. Additionally, you can have a session as a guest user without logging in.
|
Next step
Proceed to the authentication method for your preferred client:
- Mobile application. Token-based authentication.
- Third-party application. OAuth-based authentication.
- JavaScript widget on the Magento Admin or storefront. Session-based authentication.
Find us on