OAuth Authentication

Introduction

The Etsy API uses OAuth 1.0 to give developers access to an Etsy member's private account data. The OAuth approach is three-legged:

1. Using the Etsy API, an app requests a set of temporary credentials (also known as a "request token".) These are not yet associated with any specific Etsy member's account.
2. The app directs the member to a page on Etsy, where the temporary credentials are approved and linked to the member's account.
3. Using the API, the app exchanges the temporary credentials for permanent token credentials (also known as an "access token".) These credentials give the app limited access to the member's account using the API.

In addition, a proprietary extension to the OAuth protocol called "permission scopes" allows apps to be more specific about the operations they intend to perform against an Etsy member's account. This means that apps that, for instance, only intend to look at a member's sales history and not upload or change the member's listings, can request only the permissions they intend to use. This protects the member's account against abuse.

Permission Scopes

Methods and fields in the Etsy API are tagged with "permission scopes" that control what operations can be performed and what data can be read with a given set of OAuth credentials:

Apps that obtain OAuth credentials without specifying at least one of the above scopes will have a level of access that is not much different from apps using basic, API-key-based authentication. To take advantage of Etsy's read-write API, at least one of the above scopes should be specified in the next step.

Obtaining Temporary Credentials

The first step in OAuth is to obtain temporary credentials. You'll send us a request with your consumer key, signed with your shared secret; we'll check that your consumer key and shared secret match up, and return temporary credentials including an OAuth token and token secret. These are used to produce a secure login URL to the OAuth signin page on the Etsy site using your consumer key and OAuth token provided by the call. This way, your application can authenticate against an Etsy member's account without requesting a username or password.

NOTE: we use your API key as the OAuth consumer key, and your API key's shared secret as the consumer shared secret.

In addition, you should pass one or more permission scopes from the table in the previous section, depending on what aspects of the member's account you'd like to access. These are passed using the proprietary field scope in the temporary credentials request. Multiple permission scopes should be separated with spaces.

Using the PHP OAuth library this would look something like the following:

// instantiate the OAuth object
// OAUTH_CONSUMER_KEY and OAUTH_CONSUMER_SECRET are constants holding your key and secret
// and are always used when instantiating the OAuth object 
$oauth = new OAuth(OAUTH_CONSUMER_KEY, OAUTH_CONSUMER_SECRET);

// make an API request for your temporary credentials
$req_token = $oauth->getRequestToken("https://openapi.etsy.com/v2/oauth/request_token?scope=email_r%20listings_r", 'oob', "GET");

print $req_token['login_url']."\n";

The response will contain your temporary credentials, including a field called login_url with a URL that will allow the Etsy member to approve your account access. In your finished application, you could present this URL for the member to click on, open the URL in a new browser window, or automatically perform a redirect.

Authorizing the Request

When the Etsy member visits the OAuth authorization page, she or he will see a message describing the OAuth signin process, and a detailed description of the permission scopes you've specified for the OAuth credentials:

Once the member clicks on "Allow Access", she or he is presented with a verifier token. They'll need to return to your application and enter this verifier token by hand:

However, you will probably want the member redirected back to your app automatically. If you provide a callback URL as the second parameter to getRequestToken(), a successful sign-in will redirect to that page in your app. (In the getRequestToken() method above, we're passing 'oob' for the second parameter—this is equivalent to passing null for the callback, because null values are not allowed.) The callback URL will be passed two query string parameters called oauth_verifier (for the verifier value) and oauth_token, which is the token from the temporary credentials you already received. (The token secret from step one is not passed in the URL, and you will have to store the secret so that you can properly sign the request when obtaining token credentials in the next step.)

Note: There is a small window of time between obtaining temporary credentials, and authorizing them against a member's account. If this window is exceeded, you will need to restart the OAuth process.

Obtaining Token Credentials

The next step is to request OAuth token credentials. You will sign the request with the OAuth token and secret from the temporary credentials, and the OAuth verifier. If you passed a callback URL in the first step, the temporary credentials and verifier will be returned as GET params in the callback URL. You'll need to store the secret from step 1 somewhere, as that is not passed in the parameter list to your callback. (In our example, we're storing the secret in a cookie, but this is not recommended for non-HTTPS apps. Use a database like MySQL, or a local file on disk instead.) Using the PHP library, you can then request token credentials like so:

// get temporary credentials from the url
$request_token = $_GET['oauth_token'];

// get the temporary credentials secret - this assumes you set the request secret  
// in a cookie, but you may also set it in a database or elsewhere
$request_token_secret = $_COOKIE['request_secret'];

// get the verifier from the url
$verifier = $_GET['oauth_verifier'];

$oauth = new OAuth(OAUTH_CONSUMER_KEY, OAUTH_CONSUMER_SECRET);

// set the temporary credentials and secret
$oauth->setToken($request_token, $request_token_secret);

try {
    // set the verifier and request Etsy's token credentials url
    $acc_token = $oauth->getAccessToken("https://openapi.etsy.com/v2/oauth/access_token", null, $verifier, "GET");
} catch (OAuthException $e) {
    error_log($e->getMessage());
}

The array returned from the getAccessToken() call, if successful, should contain your oauth_token and oauth_token_secret. These will remain valid until the member revokes access to your application, and they can be reused for this member from this point on.

Note: There is a small window of time from when the member signs in to receive the verifier token and when you can request the OAuth token credentials. If this window is exceeded, this call will fail.

Making an Authorized Request to the API

You can use the OAuth token credentials from the previous steps to make calls for that authenticated member. The setToken() call will now set these final tokens and make the call to the Etsy API. In the URL here, __SELF__ is shorthand for the logged-in member's ID. The API will fill that in for you.

$access_token = // get from db
$access_token_secret = // get from db

$oauth = new OAuth(OAUTH_CONSUMER_KEY, OAUTH_CONSUMER_SECRET,
                   OAUTH_SIG_METHOD_HMACSHA1, OAUTH_AUTH_TYPE_URI);
$oauth->setToken($access_token, $access_token_secret);

try {
    $data = $oauth->fetch("https://openapi.etsy.com/v2/users/__SELF__", null, OAUTH_HTTP_METHOD_GET);
    $json = $oauth->getLastResponse();
    print_r(json_decode($json, true));
    
} catch (OAuthException $e) {
    error_log($e->getMessage());
    error_log(print_r($oauth->getLastResponse(), true));
    error_log(print_r($oauth->getLastResponseInfo(), true));
    exit;
}

The token credentials you receive for a member's account do not expire, and can be used over and over again to make authenticated API requests. You should keep the token secret in a secure location and never send it as a plaintext parameter (it's only used for signing your requests, and never needs to be sent in an API request on its own.) You will not need to step the Etsy member through the OAuth authorization again; unless she or he decides to revoke access for your application, or you unless you add features to your app that require additional permission scopes. In these cases, you will need to discard your old token credentials and obtain new ones for the member.

Authorized PUT/POST Requests

When making an authorized PUT/POST request to the API, form data should be placed in the post body, and the request should specify a Content-Type header of application/x-www-form-urlencoded. This behavior happens automatically when specifying OAUTH_HTTP_METHOD_PUT or OAUTH_HTTP_METHOD_POST using PHP's OAuth library, but you may have to specify it manually with other clients.

Below is what a request should look like. Note: for clarity, this example doesn't include OAuth parameters, but your requests must include them.

HTTP Method:
PUT

Path:
https://openapi.etsy.com/v2/listings/12345678/inventory

Headers:
Content-Type: application/x-www-form-urlencoded

Post body:
products=[{"product_id":91011,"property_values":[],"offerings":[{"offering_id":141516,"price":"5.00","quantity":1}]}]

Checking Permission Scopes After Authentication

A meta resource is available to determine what scopes the current token has permission for: /v2/oauth/scopes. You may want to store this information on the client side on obtaining the access token, but if you haven't stored it or need to access it again, this resource is available. Access is simple and similar to any other authenticated request made with the Etsy API. Example:

$access_token = // get from db
$access_token_secret = // get from db

$oauth = new OAuth(OAUTH_CONSUMER_KEY, OAUTH_CONSUMER_SECRET,
                   OAUTH_SIG_METHOD_HMACSHA1, OAUTH_AUTH_TYPE_URI);
$oauth->setToken($access_token, $access_token_secret);

try {
    $data = $oauth->fetch("https://openapi.etsy.com/v2/oauth/scopes", null, OAUTH_HTTP_METHOD_GET);
    $json = $oauth->getLastResponse();
    print_r(json_decode($json, true));

} catch (OAuthException $e) {
    error_log($e->getMessage());
    error_log(print_r($oauth->getLastResponse(), true));
    error_log(print_r($oauth->getLastResponseInfo(), true));
    exit;
}

Array
(
    [count] => 4
    [results] => Array
        (
            [0] => email_r
            [1] => listings_r
            [2] => listings_w
            [3] => listings_d
        )

    [params] =>
    [type] => ArrayString
    [pagination] => Array
        (
        )

)