Token-based authentication
To make a web API call from a client such as a mobile application, you must supply an access token on the call. The token acts like an electronic key that lets you access the API.
Magento issues the following types of access tokens:
| Token type | Description | Default lifetime |
|---|---|---|
| Integration | The merchant determines which Magento resources the integration has access to. | Indefinite. It lasts until it is manually revoked. |
| Admin | The merchant determines which Magento resources an admin user has access to. | 4 hours |
| Customer | Magento grants access to resources with the anonymous or self permission. Merchants cannot edit these settings. |
1 hour |
Integration tokens
When a merchant creates and activates an integration, Magento generates a consumer key, consumer secret, access token, and access token secret. All of these entities are used for OAuth-based authentication, but token-based authentication requires only the access token.
Use the following steps to generate an access token:
- Log in to Admin and click System > Extensions > Integrations to display the Integrations page.
- Click Add New Integration to display the New Integration page.
- Enter a unique name for the integration in the Name field. Then enter your admin password in the Your Password field. Leave all other fields blank.
- Click the API tab. Select the Magento resources the integration can access. You can select all resources, or select a custom list.
- Click Save to save your changes and return to the Integrations page.
- Click the Activate link in the grid that corresponds to the newly-created integration.
-
Click Allow . A dialog similar to the following displays:
The access token can be used in all calls made on behalf of the integration.
Admin and customer access tokens
Magento provides a separate token service for administrators and customers. When you request a token from one of these services, the service returns a unique access token in exchange for the username and password for a Magento account.
The Magento web API framework allows guest users to access resources that are configured with the permission level of anonymous. 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. Restricting access to anonymous web APIs contains a list of APIs that do not require a token.
The following table lists endpoints and services that can be used to get an authentication token. Admin accounts must be authenticated with a two factor authentication provider. Some providers may require multiple calls.
| Token type | REST | SOAP |
|---|---|---|
| Admin with Google Authenticator | POST /V1/tfa/provider/google/authenticate |
twoFactorAuthGoogleAuthenticateV1 |
| Admin with Duo Security | POST /V1/tfa/provider/duo-security/authenticate |
twoFactorAuthDuoAuthenticateV1 |
| Admin with Authy | POST /V1/tfa/provider/authy/authenticate |
twoFactorAuthAuthyAuthenticateV1 |
| Admin with U2F | POST /V1/tfa/provider/u2fkey/verify |
twoFactorAuthU2fKeyAuthenticateV1 |
| Customer | POST /V1/integration/customer/token |
integrationCustomerTokenServiceV1 |
For most web API calls, you supply this token in the Authorization request header with the Bearer HTTP authorization scheme to prove your identity. By default, an admin token is valid for 4 hours, while a customer token is valid for 1 hour. You can change these values from Admin by selecting Stores > Settings > Configuration > Services > OAuth > Access Token Expiration.
A cron job that runs hourly removes all expired tokens.
Request a token
A access token request contains three basic elements:
| 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 POST <host>/rest/<store_code>/V1/integration/customer/token endpoint:The server is magento.host/index.php/,the web service is rest.and the resource is /V1/integration/customer/token. |
| Content type | The content type of the request body. Set this value to either "Content-Type:application/json" or "Content-Type:application/xml". |
| Credentials | The username and password for a Magento account. To specify these credentials in a JSON request body, include code similar to the following in the call: {"username":"<USER-NAME>;", "password":"<PASSWORD>"}To specify these credentials in XML, include code similar to the following in the call: <login><username>customer1</username><password>customer1pw</password></login> |
Examples
The following image shows a token request for the admin account using a REST client:
The following example uses the curl command to request a token for a customer account:
1
2
3
curl -X POST "https://magento.host/index.php/rest/V1/integration/customer/token" \
-H "Content-Type:application/json" \
-d '{"username":"customer@example.com", "password":"customer_password"}'
The following example makes the same request with XML for a customer account token:
1
2
3
curl -X POST "http://magento.vg/index.php/rest/V1/integration/customer/token" \
-H "Content-Type:application/xml" \
-d "<login><username>customer1</username><password>customer1pw</password></login>"
For more information about the curl command, see Use cURL to run the request
Authentication token response
A successful request returns a response body with the token, as follows:
asdf3hjklp5iuytre
Use the token in a Web API request
Any web API call that accesses a resource that requires a permission level higher than anonymous must contain the authentication token in the header To do this, specify a HTTP header in the following format:
Authorization: Bearer <authentication token>
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"
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"
Related topics