---
layout: m1x_rest
title: Authentication
---

<ul class="introduction-menu">
    <li><a href='#OAuthAuthentication-Introduction'><strong>Introduction</strong></a></li>
    <li><a href='#OAuthAuthentication-UsingOAuth'>Using OAuth</a></li>
    <li><a href='#OAuthAuthentication-WhyDoYouNeedOAuth%3F'>Why Do You Need OAuth?</a></li>
    <li><a href='#OAuthAuthentication-OAuthDefinitions'>OAuth Definitions</a></li>
    <li><a href='#OAuthAuthentication-OAuthProcess'>OAuth Process</a>
        <ul>
            <li><a href='#OAuthAuthentication-RegisteringanApplication'>Registering an Application</a></li>
            <li><a href='#OAuthAuthentication-AuthenticationEndpoints'>Authentication Endpoints</a>
                <ul>
                    <li><a href='#OAuthAuthentication-GettinganUnauthorizedRequestToken'>Getting an Unauthorized Request Token</a></li>
                    <li><a href='#OAuthAuthentication-UserAuthorization'>User Authorization</a></li>
                    <li><a href='#OAuthAuthentication-GettinganAccessToken'>Getting an Access Token</a></li>
                </ul>
            </li>
        </ul></li>
    <li><a href='#OAuthAuthentication-OAuthErrorCodes'>OAuth Error Codes</a></li>
    <li><a href='#OAuthAuthentication-PHPExamples'>PHP Examples</a>
        <ul>
            <li><a href='#OAuthAuthentication-RetrievethelistofproductsforAdminuserwithOAuthauthentication'>Retrieve the list of products for Admin user with OAuth authentication</a></li>
            <li><a href='#OAuthAuthentication-RetrievethelistofproductsforCustomeruserwithOAuthauthentication'>Retrieve the list of products for Customer user with OAuth authentication</a></li>
        </ul>
    </li>
</ul>


<h2><a name="OAuthAuthentication-Introduction"></a>Introduction</h2>

<p>In most cases, the third-party application must be authenticated to use the Magento API. But users never reveal their credentials to the application to preserve their privacy. So, the question is as follows: how is your application going to authenticate users if it does not know user credentials. OAuth is the solution.</p>

<p>Magento authentication is based on OAuth, an open standard for secure API authentication. OAuth is a token-passing mechanism that allows users to control which applications have access to their data without revealing their passwords or other credentials.</p>

<p>The OAuth concept lies in three basic elements that can be easily described in the following picture:</p>


<img src="{{ site.baseurl }}common/images/m1x/rest_oauth1.png" alt=""/>

<p>To learn more about OAuth, you can visit the official <a href="http://oauth.net/">OAuth</a> site.</p>


<h2><a name="OAuthAuthentication-UsingOAuth"></a>Using OAuth</h2>

<p>The current API supports OAuth 1.0a.</p>

<p>The OAuth authentication works by asking the user to authorize their application. When the user authorizes the application, the application can access that user protected resources by using an access token. This token will be used in each further request. Access tokens are long-lived and will not expire unless the user revokes access to the application.</p>

<p>OAuth is completely invisible for the site visitors.</p>

<h2><a name="OAuthAuthentication-WhyDoYouNeedOAuth%3F"></a>Why Do You Need OAuth?</h2>

<p>Magento uses OAuth to allow access to its data. You need to use OAuth if you want to use any of the following Magento APIs:</p>

<ul>
	<li>Products</li>
	<li>Inventory</li>
	<li>Orders</li>
	<li>Customers</li>
	<li>Customer Addresses</li>
	<li>Categories<br/>
and a lot more</li>
</ul>



<h2><a name="OAuthAuthentication-OAuthDefinitions"></a>OAuth Definitions</h2>

<p>There are some definitions you need to get familiar with before you start using OAuth. These are as follows:</p>
<ul>
	<li><b>User</b> &#45; A customer who has an account with Magento and can use the services via the Magento API.</li>
	<li><b>Consumer</b> &#45; A third-party application that uses OAuth to access the Magento API. This application must be registered in the Magento system to receive the Consumer Key and Consumer Secret.</li>
	<li><b>Consumer Key</b> &#45; A value used by the Consumer to identify itself with Magento.</li>
	<li><b>Consumer Secret</b> &#45; A secret used by the Consumer to guarantee the ownership of the Consumer Key. This value is not passed in requests.</li>
	<li><b>Request Token</b> &#45; A value used by the Consumer to obtain authorization from the User (when needed). The Request Token is exchanged for an Access Token when permission is granted.</li>
	<li><b>Access Token</b> &#45; A value used by the Consumer to call Magento APIs on behalf of the User.</li>
</ul>



<h2><a name="OAuthAuthentication-OAuthProcess"></a>OAuth Process</h2>

<p>The OAuth process consists of several steps:</p>
<ul>
	<li>Getting an Unauthorized Request Token.</li>
	<li>Requesting user authorization.</li>
	<li>Getting an Access Token by exchanging the Request Token for it.</li>
</ul>

<img src="{{ site.baseurl }}common/images/m1x/rest_oauth2.png" alt=""/>

<p>The application that requires access to data is known as the Consumer and Magento is the Service Provider.</p>


<h3><a name="OAuthAuthentication-RegisteringanApplication"></a>Registering an Application</h3>

<p>Before starting to make API requests, you need to register the application. After the registration, you will receive the Consumer Key that will identify you in Magento. Also, you will receive a Consumer Secret. This secret will be used when requesting for a Request Token.</p>

<p>You can register your application by selecting <b>System</b> &gt; <b>Web Services</b> &gt; <b>REST - OAuth Consumers</b> and clicking <b>Add New</b> in the Admin Panel.</p>

<p>When registering the application, you also need to define the callback URL, to which the user will be redirected after he/she successfully authorizes your application.</p>

<h3><a name="OAuthAuthentication-AuthenticationEndpoints"></a>Authentication Endpoints</h3>

<p>The authentication endpoints include the following ones:</p>

<ul>
	<li><b>/oauth/initiate</b> &#45; this endpoint is used for retrieving the Request Token.</li>
	<li><b>/oauth/authorize</b> &#45; this endpoint is used for user authorization (Customer).</li>
	<li><b>/admin/oauth_authorize</b> &#45; this endpoint is used for user authorization (Admin).</li>
	<li><b>/oauth/token</b> &#45; this endpoint is used for retrieving the Access Token.</li>
</ul>


<p>Also, the simple form can be used for authentication. To use a simple form, add the /simple endpoint to the authentication endpoint. For example: /oauth/authorize/simple</p>


<h4><a name="OAuthAuthentication-GettinganUnauthorizedRequestToken"></a>Getting an Unauthorized Request Token</h4>

<p>The first step to authenticate the user is to retrieve a Request Token from Magento. This is a temporary token that will be exchanged for the Access Token.</p>



<table><tbody>
<tr>
<th> <b>Endpoint</b>: </th>
<td> /oauth/initiate </td>
</tr>
<tr>
<th> <b>Description</b>: </th>
<td> The first step of authentication. Allows you to obtain the Request Token used for the rest of the authentication process. </td>
</tr>
<tr>
<th> <b>Method</b>: </th>
<td> POST </td>
</tr>
<tr>
<th> <b>Returns</b>: </th>
<td> Request Token </td>
</tr>
<tr>
<th> <b>Sample Response</b>: </th>
<td> oauth_token=4cqw0r7vo0s5goyyqnjb72sqj3vxwr0h&amp;oauth_token_secret=rig3x3j5a9z5j6d4ubjwyf9f1l21itrr&amp;oauth_callback_confirmed=true </td>
</tr>
</tbody></table>


<p>The following request parameters should be present in the Authorization header:</p>
<ul>
	<li>oauth_callback - an URI to which the Service Provider will redirect the resource owner (user) after the authorization is complete.</li>
	<li>oauth_consumer_key - the Consumer Key value, retrieved after the registration of the application.</li>
	<li>oauth_nonce - a random value, uniquely generated by the application.</li>
	<li>oauth_signature_method - name of the signature method used to sign the request. Can have one of the following values: HMAC-SHA1, RSA-SHA1, and PLAINTEXT.</li>
	<li>oauth_signature - a generated value (signature).</li>
	<li>oauth_timestamp - a positive integer, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.</li>
	<li>oauth_version - OAuth version.</li>
</ul>


<h4><a name="OAuthAuthentication-UserAuthorization"></a>User Authorization</h4>

<p>The second step is to request user authorization. After receiving the Request Token from Magento, the application provides an authorization page to the user. The only required parameter for this step is the Request Token (oauth_token value) received from the previous step. The endpoint is followed by an oauth_token parameter with the value set to the oauth_token value.</p>

<p>After this, the user is asked to enter their credentials and authorize. When the user is granted the access, he/she is redirected to the URL specified in the oauth_callback parameter. This URL is followed by two parameters:</p>
<ul>
	<li>oauth_token - the Request Token value.</li>
	<li>oauth_verifier - a verification code that is tied to the Request Token.</li>
</ul>




<table><tbody>
<tr>
<th> <b>Endpoint</b>: </th>
<td> /oauth/authorize </td>
</tr>
<tr>
<th> <b>Description</b>: </th>
<td> The second step of authentication. Without the user authorization in this step, it is impossible for your application to obtain an Access Token. </td>
</tr>
<tr>
<th> <b>Method</b>: </th>
<td> GET </td>
</tr>
<tr>
<th> <b>Sample Response</b>: </th>
<td> /callback?oauth_token=tz2kmxyf3lagl3o95xnox9ia15k6mpt3&amp;oauth_verifier=cbwwh03alr5huiz5c76wi4l21zf05eb0 </td>
</tr>
</tbody></table>



<h4><a name="OAuthAuthentication-GettinganAccessToken"></a>Getting an Access Token</h4>

<p>The final third authentication step. After the application access is authorized, the application needs to exchange the Request Token for an Access Token. For this step, you will need the Request Token (the oauth_token and oauth_token_secret values) and the oauth_verifier value from the previous step.</p>



<table><tbody>
<tr>
<th> <b>Endpoint</b>: </th>
<td> /oauth/token </td>
</tr>
<tr>
<th> <b>Description</b>: </th>
<td> The third step of authentication. Getting an Access Token. </td>
</tr>
<tr>
<th> <b>Method</b>: </th>
<td> POST </td>
</tr>
<tr>
<th> <b>Returns</b>: </th>
<td> An access token and the corresponding access token secret, URL-encoded. </td>
</tr>
<tr>
<th> <b>Sample Response</b>: </th>
<td> oauth_token=0lnuajnuzeei2o8xcddii5us77xnb6v0&amp;oauth_token_secret=1c6d2hycnir5ygf39fycs6zhtaagx8pd </td>
</tr>
</tbody></table>


<p>The following components should be present in the Authorization header:</p>
<ul>
	<li>oauth_consumer_key - the Consumer Key value provided after the registration of the application.</li>
	<li>oauth_nonce - a random value, uniquely generated by the application.</li>
	<li>oauth_signature_method - name of the signature method used to sign the request. Can have one of the following values: HMAC-SHA1, RSA-SHA1, and PLAINTEXT.</li>
	<li>oauth_signature - a generated value (signature).</li>
	<li>oauth_timestamp - a positive integer, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.</li>
	<li>oauth_token - the oauth_token value (Request Token) received from the previous steps.</li>
	<li>oauth_verifier - the verification code that is tied to the Request Token.</li>
	<li>oauth_version - OAuth version.</li>
</ul>



<p>The response will contain the following response parameters:</p>
<ul>
	<li>oauth_token - the Access Token that provides access to protected resources.</li>
	<li>oauth_token_secret - the secret that is associated with the Access Token.</li>
</ul>




<h2><a name="OAuthAuthentication-OAuthErrorCodes"></a>OAuth Error Codes</h2>

<p>When the third-party application performs invalid requests to Magento, the following errors related to OAuth can occur:</p>


<table><tbody>
<tr>
<th> HTTP Code </th>
<th> Error Code </th>
<th> Text Representation </th>
<th> Description </th>
</tr>
<tr>
<td> 400 </td>
<td> 1 </td>
<td> version_rejected </td>
<td> This error is used when the oauth_version parameter does not correspond to the "1.0a" value. </td>
</tr>
<tr>
<td> 400 </td>
<td> 2 </td>
<td> parameter_absent<br class="atl-forced-newline" /> </td>
<td> This error is used there is no required parameter in the request. The name of the missing parameter is specified additionally in the response. </td>
</tr>
<tr>
<td> 400 </td>
<td> 3 </td>
<td> parameter_rejected<br class="atl-forced-newline" /> </td>
<td> This error is used when the type of the parameter or its value does not meet the protocol requirements (e.g., array is passed instead of the string). </td>
</tr>
<tr>
<td> 400 </td>
<td> 4 </td>
<td> timestamp_refused<br class="atl-forced-newline" /> </td>
<td> This error is used if there is incorrect value of the timestamp in the oauth_timestamp parameter. </td>
</tr>
<tr>
<td> 401 </td>
<td> 5 </td>
<td> nonce_used<br class="atl-forced-newline" /> </td>
<td> This error is used if the nonce-timestamp combination has already been used. </td>
</tr>
<tr>
<td> 400 </td>
<td> 6 </td>
<td> signature_method_rejected<br class="atl-forced-newline" /> </td>
<td> This error is used for unsupported signature method. The following methods are supported: HMAC-SHA1, RSA-SHA1, and PLAINTEXT. </td>
</tr>
<tr>
<td> 401 </td>
<td> 7 </td>
<td> signature_invalid<br class="atl-forced-newline" /> </td>
<td> This error is used if the signature is invalid. </td>
</tr>
<tr>
<td> 401 </td>
<td> 8 </td>
<td> consumer_key_rejected<br class="atl-forced-newline" /> </td>
<td> This error is used if the Consumer Key has incorrect length or does not exist. </td>
</tr>
<tr>
<td> 401 </td>
<td> 9 </td>
<td> token_used<br class="atl-forced-newline" /> </td>
<td> This error is used if there is an attempt of authorization of an already authorized token or an attempt to exchange a not temporary token for a permanent one. </td>
</tr>
<tr>
<td> 401 </td>
<td> 10 </td>
<td> token_expired<br class="atl-forced-newline" /> </td>
<td> This error is used if the temporary token has expired. At the moment, the mechanism of expiration of temporary tokens is not implemented and the current error is not used. </td>
</tr>
<tr>
<td> 401 </td>
<td> 11 </td>
<td> token_revoked<br class="atl-forced-newline" /> </td>
<td> This error is used if the token is revoked by the user who authorized it. </td>
</tr>
<tr>
<td> 401 </td>
<td> 12 </td>
<td> token_rejected<br class="atl-forced-newline" /> </td>
<td> This error is used if the token is not valid, or does not exist, or is not valid for using in the current type of request. </td>
</tr>
<tr>
<td> 401 </td>
<td> 13 </td>
<td> verifier_invalid<br class="atl-forced-newline" /> </td>
<td> This error is used if the confirmation string does not correspond to the token. </td>
</tr>
</tbody></table>




<h2><a name="OAuthAuthentication-PHPExamples"></a>PHP Examples</h2>

<h3><a name="OAuthAuthentication-RetrievethelistofproductsforAdminuserwithOAuthauthentication"></a>Retrieve the list of products for Admin user with OAuth authentication</h3>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">

{% highlight PHP %}
<?php
/**
 * Example of retrieving the products list using Admin account via Magento REST API. OAuth authorization is used
 * Preconditions:
 * 1. Install php oauth extension
 * 2. If you were authorized as a Customer before this step, clear browser cookies for 'yourhost'
 * 3. Create at least one product in Magento
 * 4. Configure resource permissions for Admin REST user for retrieving all product data for Admin
 * 5. Create a Consumer
 */
// $callbackUrl is a path to your file with OAuth authentication example for the Admin user
$callbackUrl = "http://yourhost/oauth_admin.php";
$temporaryCredentialsRequestUrl = "http://yourhost/oauth/initiate?oauth_callback=" . urlencode($callbackUrl);
$adminAuthorizationUrl = 'http://yourhost/admin/oAuth_authorize';
$accessTokenRequestUrl = 'http://yourhost/oauth/token';
$apiUrl = 'http://yourhost/api/rest';
$consumerKey = 'yourconsumerkey';
$consumerSecret = 'yourconsumersecret';

session_start();
if (!isset($_GET['oauth_token']) && isset($_SESSION['state']) && $_SESSION['state'] == 1) {
    $_SESSION['state'] = 0;
}
try {
    $authType = ($_SESSION['state'] == 2) ? OAUTH_AUTH_TYPE_AUTHORIZATION : OAUTH_AUTH_TYPE_URI;
    $oauthClient = new OAuth($consumerKey, $consumerSecret, OAUTH_SIG_METHOD_HMACSHA1, $authType);
    $oauthClient->enableDebug();

    if (!isset($_GET['oauth_token']) && !$_SESSION['state']) {
        $requestToken = $oauthClient->getRequestToken($temporaryCredentialsRequestUrl);
        $_SESSION['secret'] = $requestToken['oauth_token_secret'];
        $_SESSION['state'] = 1;
        header('Location: ' . $adminAuthorizationUrl . '?oauth_token=' . $requestToken['oauth_token']);
        exit;
    } else if ($_SESSION['state'] == 1) {
        $oauthClient->setToken($_GET['oauth_token'], $_SESSION['secret']);
        $accessToken = $oauthClient->getAccessToken($accessTokenRequestUrl);
        $_SESSION['state'] = 2;
        $_SESSION['token'] = $accessToken['oauth_token'];
        $_SESSION['secret'] = $accessToken['oauth_token_secret'];
        header('Location: ' . $callbackUrl);
        exit;
    } else {
        $oauthClient->setToken($_SESSION['token'], $_SESSION['secret']);

        $resourceUrl = "$apiUrl/products";
        $oauthClient->fetch($resourceUrl, array(), 'GET', array('Content-Type' => 'application/json'));
        $productsList = json_decode($oauthClient->getLastResponse());
        print_r($productsList);
    }
} catch (OAuthException $e) {
    print_r($e->getMessage());
    echo "&lt;br/&gt;";
    print_r($e->lastResponse);
}
{% endhighlight %}


<h3><a name="OAuthAuthentication-RetrievethelistofproductsforCustomeruserwithOAuthauthentication"></a>Retrieve the list of products for Customer user with OAuth authentication</h3>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div id="root">
		<pre class="theme: Default; brush: php; gutter: false">&lt;?php
/**
 * Example of retrieving the products list using Customer account via Magento REST API. OAuth authorization is used
 * Preconditions:
 * 1. Install php oauth extension
 * 2. If you were authorized as an Admin before this step, clear browser cookies for 'yourhost'
 * 3. Create at least one product in Magento and enable it for viewing in the frontend
 * 4. Configure resource permissions for Customer REST user for retrieving all product data for Customer
 * 5. Create a Consumer
 */
// $callbackUrl is a path to your file with OAuth authentication example for the Customer user
$callbackUrl = "http://yourhost/oauth_customer.php";
$temporaryCredentialsRequestUrl = "http://yourhost/oauth/initiate?oauth_callback=" . urlencode($callbackUrl);
$customerAuthorizationUrl = 'http://yourhost/oauth/authorize';
$accessTokenRequestUrl = 'http://yourhost/oauth/token';
$apiUrl = 'http://yourhost/api/rest';
$consumerKey = 'yourconsumerkey';
$consumerSecret = 'yourconsumersecret';

session_start();
if (!isset($_GET['oauth_token']) && isset($_SESSION['state']) && $_SESSION['state'] == 1) {
    $_SESSION['state'] = 0;
}
try {
    $authType = ($_SESSION['state'] == 2) ? OAUTH_AUTH_TYPE_AUTHORIZATION : OAUTH_AUTH_TYPE_URI;
    $oauthClient = new OAuth($consumerKey, $consumerSecret, OAUTH_SIG_METHOD_HMACSHA1, $authType);
    $oauthClient->enableDebug();

    if (!isset($_GET['oauth_token']) && !$_SESSION['state']) {
        $requestToken = $oauthClient->getRequestToken($temporaryCredentialsRequestUrl);
        $_SESSION['secret'] = $requestToken['oauth_token_secret'];
        $_SESSION['state'] = 1;
        header('Location: ' . $customerAuthorizationUrl . '?oauth_token=' . $requestToken['oauth_token']);
        exit;
    } else if ($_SESSION['state'] == 1) {
        $oauthClient->setToken($_GET['oauth_token'], $_SESSION['secret']);
        $accessToken = $oauthClient->getAccessToken($accessTokenRequestUrl);
        $_SESSION['state'] = 2;
        $_SESSION['token'] = $accessToken['oauth_token'];
        $_SESSION['secret'] = $accessToken['oauth_token_secret'];
        header('Location: ' . $callbackUrl);
        exit;
    } else {
        $oauthClient->setToken($_SESSION['token'], $_SESSION['secret']);

        $resourceUrl = "$apiUrl/products";
        $oauthClient->fetch($resourceUrl, array(), 'GET', array('Content-Type' => 'application/json'));
        $productsList = json_decode($oauthClient->getLastResponse());
        print_r($productsList);
    }
} catch (OAuthException $e) {
    print_r($e->getMessage());
    echo "&lt;br/&gt;";
    print_r($e->lastResponse);
}</pre>