To make a web API call from a client such as a mobile application, you must supply an authentication token on the call. The token acts like an electronic key that lets you access the API.
You request a token from the Magento token service at the REST endpoint that is defined for your user type. The token service returns a unique authentication token in exchange for a user name and password for a Magento account.
When you make web API calls, you supply this token in the Authorization
request header with the Bearer
HTTP authorization scheme to prove your identity. The token never expires but it can be revoked.
To request an authentication token and learn how to use it in web API calls, read these sections:
cURL command syntax
The examples on this page use cURL commands. For more information, see How cURL commands work.
To use cURL to request an authentication token from the Magento token service, use this syntax:
curl -X POST "https://magento.host/index.php/rest/V1/integration/{customer|admin}/token" \ -H "Content-Type:application/json" \ -d '{"username":"<USER-NAME>", "password":"<PASSWORD>"}'
This syntax shows a JSON request body. Alternatively, you can specify an XML request body.
The components in the command syntax are:
Component | Specifies |
---|---|
Endpoint |
A combination of the server that fulfills the request, the web service, and the resource against which the request is being made. For example, in the For an admin user, the resource is |
Content type |
The content type of the request body. To specify a JSON request body, include |
Credentials |
The user name and password for a Magento account. To specify these credentials in a JSON request body, include |
XML request body
To specify an XML request body:
- Append
.xml
to the endpoint. - Include the
Content-Type:application/xml
header in the call. - Use the
-d
option to specify the XML-formatted request body.
For example:
curl -X POST "https://magento.host/index.php/rest/V1/integration/customer/token" \ -H "Content-Type:application/xml" \ -d '<login><username>user_example</username><password>123123q</password></login>'
Authentication token request
To request an authentication token for a customer user for the REST web API:
curl -X POST "https://magento.host/index.php/rest/V1/integration/customer/token" \ -H "Content-Type:application/json" \ -d '{"username":"user_example", "password":"123123q"}'
To request an authentication token for an admin user for the REST web API:
curl -X POST "https://magento.host/index.php/rest/V1/integration/admin/token" \ -H "Content-Type:application/json" \ -d '{"username":"user_example", "password":"123123q"}'
Authentication token response
A successful request returns a response body with the token, as follows:
"asdf3hjklp5iuytre"
Web API request
You must specify an authentication token in a web API call for a resource for which you are authorized.
You specify the token in the Authorization
request header with the Bearer
HTTP authorization scheme.
Customer access
Customers can access only resources with self
permissions.
For example, to make a web API call with a customer token:
curl -X GET "http://magento.ll/index.php/rest/V1/customers/me" \ -H "Authorization: Bearer asdf3hjklp5iuytre"
Admin access
Admins can access any resources for which they are authorized.
For example, to make a web API call with an admin token:
curl -X GET "http://magento.ll/index.php/rest/V1/customers/2" \ -H "Authorization: Bearer vbnf3hjklp5iuytre"
Guest access
The Magento web API framework allows guest users to access resources that are configured with anonymous permission. Guest users are users who the framework cannot authenticate through existing authentication mechanisms. As a guest user, you do not need to, but you can, specify a token in a web API call for a resource with anonymous permission.
Find us on