Token-based authentication

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
• Authentication token request
• Authentication token response
• Web API request

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:

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.

Next step

• Step 2. Construct a request

Related topic

• Configure services as web APIs