layout: default

group: get-started

subgroup: 40_Authentication

title: Token-based authentication

menu_title: Token-based authentication

menu_order: 1

version: 2.0

github_link: get-started/authentication/gs-authentication-token.md

redirect_from: /guides/v1.0/get-started/authentication/gs-authentication-token.html

To make a web {% glossarytooltip 786086f2-622b-4007-97fe-2c19e5283035 %}API{% endglossarytooltip %} 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.

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 authentication token in exchange for the user name 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]({{page.baseurl}}rest/anonymous-api-security.html) contains a list of APIs that do not require a token.

Use the following calls to get an authentication token:

Request|REST|SOAP

---|---|---

Get an admin token | `POST /V1/integration/admin/token` | `integrationAdminTokenServiceV1`

Get a customer token | `POST /V1/integration/customer/token` | `integrationCustomerTokenServiceV1`

For most {% glossarytooltip 377dc0a3-b8a7-4dfa-808e-2de37e4c0029 %}web API{% endglossarytooltip %} calls, you supply this token in the `Authorization` request header with the `Bearer` HTTP {% glossarytooltip 34ecb0ab-b8a3-42d9-a728-0b893e8c0417 %}authorization{% endglossarytooltip %} 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 > Configuration > Services > OAuth > Access Token Expiration**.

A cron job that runs hourly removes all expired tokens.

A authentication token request contains three basic elements:

<table style="width:100%">

<tr bgcolor="lightgray">

<th>Component</th>

<th>Specifies</th>

</tr>

<tr>

<td>Endpoint</td>

<td>

<p>A combination of the <i>server</i> that fulfills the request, the web service, and the <i>resource</i> against which the request is being made.</p>

<p>For example, in the <code>POST https://magento.host/index.php/rest/V1/integration/customer/token</code> endpoint:</p>

<p>The server is <code>magento.host/index.php/</code></p>

<p>the web service is <code>rest</code></p>

the resource is <code>/V1/integration/customer/token</code>.</p>

</td>

</tr>

<tr>

<td>Content&nbsp;type</td>

<td>

<p>The content type of the request body. Set this value to either <code>"Content-Type:application/json"</code> or <code>"Content-Type:application/xml"</code>.</p>

</td>

</tr>

<tr>

<td>Credentials</td>

<td>

<p>The user name and password for a Magento account.</p>

<p>To specify these credentials in a JSON request body, include <code>'{"username":"&lt;USER-NAME&gt;", "password":"&lt;PASSWORD&gt;"}'</code> in the call.</p>

<p> To specify these credentials in XML, include <code>&lt;login>&lt;username>[email protected]&lt;/username>&lt;password>customer1pw&lt;/password>&lt;/login></code> in the call.</p>

</td>

</tr>

</table>

The following image shows a token request for the {% glossarytooltip 29ddb393-ca22-4df9-a8d4-0024d75739b1 %}admin{% endglossarytooltip %} account using a REST client:


The following example uses the `curl` command to request a token for a customer account:

The following example makes the same request with {% glossarytooltip 8c0645c5-aa6b-4a52-8266-5659a8b9d079 %}XML{% endglossarytooltip %} for a customer account token:

For more information about the `curl` command, see [Use cURL to run the request]({{page.baseurl}}get-started/gs-curl.html)

A successful request returns a response body with the token, as follows:

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:

Admins can access any resources for which they are authorized.

For example, to make a web API call with an admin token:

Customers can access only resources with `self` permissions.

For example, to make a web API call with a customer token:

<h2>Related topics</h2>

[Construct a request]({{page.baseurl}}/get-started/gs-web-api-request.html)

[Configure services as web APIs]({{page.baseurl}}extension-dev-guide/service-contracts/service-to-web-service.html)

[Restricting access to anonymous web APIs]({{page.baseurl}}rest/anonymous-api-security.html)