Hatena::Grouphatenadeveloper

Get Consumer Key and Let's Start OAuth development

en/auth/apis/oauth/consumer

Get Consumer Key and Let's Start OAuth Development

This document explains a procedure to prepare developing an application using Hatena's OAuth-supported APIs. In this document, we show how-to for web applications running on web servers, but even client applications should work with the same procedure.

1. Register your application and obtain a consumer key

Register your application to Hatena and obtain a consumer key and a consumer secret to be used for OAuth access. By the key and the secret, Hatena distinguishes an access made by an application from the others, and manage per-user permissions. You can register multiple applications for free.

1.1. Get Hatena ID

You need a Hatena ID to register your application. Please register if you don't have one.

Register a Hatena ID (Free)

If you already have Hatena ID, Login with it. The following instructions assume that you are logged in with a Hatena ID.

1.2. Fill in Forms and Register Your Application

Open Settings Page for OAuth Application Developer. Accept Terms of Use, Fill in form,s and register your application. There is no review process. You can use OAuth access immediately after the registration.

In Settings Page for OAuth Application Developer, you can set your application name, website URL and application logo image. As information is shown to a user on requiring his/her permission to an OAuth access by your application, input correctly and make it easy to understand. Any false or misleading content causes the OAuth access of your application to be suspended without notification based on Terms of Use.

The registration is free. You can regsiter multiple applications, like for a development use and for a production use.

1.3. Check Consumer Key

In Settings Page for OAuth Application Developer, consumer key and consumer secret for registered applications are displayed. Write down them as they are used in your OAuth application in the following steps. Never leak consumer secret to others.


2. Get an Access Permission from a User via OAuth

OAuth authorization at Hatena obeys OAuth Protocol version 1.0a. For the details of the procedure or methods of an OAuth authorization, see RFC 5849 - The OAuth 1.0 Protocol or the following sample program. In this document, a simple procedure and Hatena specific parameters are explained.

2.1. Get a request token

First, you have to get a request token to access to the authorization URL. You need to specify a scope parameter in addition to parameters defined in the OAuth specification scope. A value includes read_public (reading public information), write_private (writing private information) and Hatena's OAuth supported APIs defines their own scopes to be required. Read the document of each API you want to use and specify an appropriate scope for it.

The URL for get request token is https://www.hatena.com/oauth/initiate. A typical request and response are the following.

# HTTPS
POST /oauth/initiate HTTP/1.1
Host: www.hatena.com
Authorization: OAuth realm="",
    oauth_callback="oob",
    oauth_consumer_key="yTVGWKqa6OiH5A%3D%3D",
    oauth_nonce="0c670efea71547422662",
    oauth_signature="lvQC7AXTRIaqxbjwVGgPlYuNaaw%3D",
    oauth_signature_method="HMAC-SHA1",
    oauth_timestamp="1291689730",oauth_version="1.0"
Content-Type: application/x-www-form-urlencoded
Content-Length: 33

scope=read_public%2Cread_private
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

oauth_token=QB%2FfqbXTpFB1GQ%3D%3D&
oauth_token_secret=M1xSNaj0mw0J%2Bksk0k7WpZiGNP4%3D&
oauth_callback_confirmed=true

(We inserted newlines For ease of read.)

Do not leak oauth_token_secret to the others.

A scope parameter you can specify is depending on your application. You can use scopes like read_public by default. You can confirm or add available List of registered applications. You can specify multiple scopes separated by comma (escaped to %2C ) as shown in the request example.

2.2. Redirect to Authorization URL

Next, to get an access permission to resources on Hatena from a user, your application should redirect user to the user to Hatena. We recommend you to redirect the user according to their device platform, as shown in the following table.

PC https://www.hatena.ne.jp/oauth/authorize
Smartphones https://www.hatena.ne.jp/touch/oauth/authorize
Old mobile-phones http://www.hatena.ne.jp/mobile/oauth/authorize

When redirect a user to Hatena, your application should add a request token as a query parameter. Your URL should look like below.

https://www.hatena.ne.jp/oauth/authorize?oauth_token=QB%2FfqbXTpFB1GQ%3D%3D

The redirected page shows consumer and scope information to the user, and the user decides whether or not to permit an access by your application.

2.3. Get an Access Token

Get an access token to use OAuth-suppoted APIs. Your application needs confirmation code called oauth_verifier. When user permits access to your application in section 2.2., Hatena redirects the user to a URL specified at oauth_callback described in section 2.1. with oauth_verifier parameter. If "oob" is specified to oauth_callback instead of a URL, you should instruct the user to input as Hatena shows the value of oauth_verifier to the user so that you can instruct the user to input the value to your applicaton.

Your application can get an access token by sending a request to https://www.hatena.com/oauth/token with a verifier you've get. A typical request/response should look like below.

# HTTPS
POST /oauth/token HTTP/1.1
Host: www.hatena.com
Authorization: OAuth realm="",
    oauth_consumer_key="yTVGWKqa6OiH5A%3D%3D",
    oauth_nonce="83600f5f92b5c5a62caf",
    oauth_signature="%2Fq%2B9Uzzat1A2WoGdGW7SZoeiUfg%3D",
    oauth_signature_method="HMAC-SHA1",oauth_timestamp="1291689733",
    oauth_token="QB%2FfqbXTpFB1GQ%3D%3D",
    oauth_verifier="G8jTZ27hPKGTZJ%2B5qQOsqlKZ",
    oauth_version="1.0"
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

oauth_token=dRsM%2BQcOhiQcow%3D%3D&
oauth_token_secret=eGt1Ym8163llDcjFeDpSQPM5Sys%3D&
url_name=sample&
display_name=Sample

(We inserted newlines For ease of read.)

Take care to not leakoauth_token_secret to the others.

You can use an access token you get here is only available for an API which accepts the scope you specified in section 2.1 to get the request token.

3. Use OAuth supported Hatena APIs

For example, we explain how to use Hatena API for OAuth Applications.

Your application can use an access token retrieved in the previous sections since http://n.hatena.com/applications/my.json requires http://n.hatena.com/applications/my.json requires read_public scope.

The following is an example request.

GET /applications/my.json HTTP/1.1
Host: n.hatena.com
Authorization: OAuth realm="",
    oauth_consumer_key="q7JnhZ3Hk8a%2FlQ%3D%3D",
    oauth_nonce="e3fcb9046a7b67a2f135",
    oauth_signature="gUXzVjtGaYBC%2BIguh2cf56Id%2BdY%3D",
    oauth_signature_method="HMAC-SHA1",
    oauth_timestamp="1291692652",
    oauth_token="dRsM%2BQcOhiQcow%3D%3D",
    oauth_version="1.0"

Sample code

In Perl

The Following code is a sample application uses Mojolicious::Lite for a Web framework, and OAuth::Lite for an OAuth library.

Save the following code (we assume oauth_consumer.pl for file name) and replace YOUR_CONSUMER_KEY and YOUR_CONSUMER_SECRET with your own consumer_key and consumer_secret.

Launch your terminal, execute

$ perl oauth_consumer.pl daemon

... then access to http://localhost:3000/ with your web browser.

In Ruby

Following code is sample application uses Sinatra for a Web framework, and OAuth for an OAuth library.

Save following code (we assume for file name) and replace YOUR_CONSUMER_KEY and YOUR_CONSUMER_SECRET with your own consumer_key and consumer_secret.

Launch your terminal, execute

$ ruby oauth_consumer.rb

... then access to http://localhost:4567/ with your web browser.

Related documents

Changelog

  • May 13, 2015 Published this document.