">mixi Developer Center (mDC)

mixi Connect

mixi Connect (English) » mixi Graph API » Authorization and Authentication Process (New Spec)

Authorization and Authentication Process (New Spec)

In order to utilize various APIs from a client program, you have to implement appropriate authorization process in compliance with OAuth 2.0 Protocol. Following the process, a user is able to see what kind of information to be referred and/or renewal by what kind of API implemented within the program (we call it "Scope"). Only upon a user's consent to the scope and authorization, the client program can obtain the information (such as Token) to access to the API.

[RFC 6749 - The OAuth 2.0 Authorization Framework]
http://tools.ietf.org/html/rfc6749

[RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage]
http://tools.ietf.org/html/rfc6750

Prerequisites

Prior to the authorization and authentication process, you have to obtain the following information:

  • Consumer key
  • Consumer secret

Please, see the Credential Information when registering the services.

Authorization and Authorization Code

At the beginning, a client program accesses to the following URLs via a web browser.

  • https://mixi.jp/connect_authorize.pl : (For PC and Smartphone)
  • http://m.mixi.jp/connect_authorize.pl : (For mobile phone, excluding the smart phone)

The following query parameters have to be specified for the access:

parametervalue
client_id Consumer key
response_type "code"
scope Scope for the authorization
display Device which shows authorization/authentication window
state This value is included into a query parameter at redirecting after a user's authorization.
If the application uses a session, this parameter should be used to verify its authenticity.
server_state Set server_state got in previous step.
These values are tied up with Authorization code in the redirect after the user's authorization.

The value of the scope parameter is specified as a string list of scopes developers want to authorize divided by a white space. Please see each pages to know available scope values.

For display parameter, you can specify a device that the authorization/authentication window to be shown.

Available valueDescription
"pc" Window for PC desktop is shown
"touch" or
"smartphone"
Window for Smart Phone is shown
"ios" This parameter is used for iOS to pass the review process by Apple.

If a device is a mobile phone (so-called Keitai), the display parameter is ignored and a window for the mobile phone is displayed. If the mobile device is a Docomo feature-phone, "guid=ON" should be appended to the URL as a query parameter.

If the session isn't verified using the state parameter, the application is vulnerable to CSRF attacks. To prevent this, place a hash (etc.) of the session ID in the state parameter, and after the authorization redirect verify that the session and state parameters match. See the link below for details.
http://tools.ietf.org/html/rfc6749#section-10.12

You can specify all parameters with URL encoded text strings. Thus, overall URL is as follows:

GET https://mixi.jp/connect_authorize.pl?client_id=908ed4da74f885a2ab&response_type=code&scope=r_profile%20r_voice&state=5c1b3eea390b53f54ad0975e9a4bbba2

With appropriate value for each parameter, authorization/authentication window should be displayed. In the case, however, a user has logged in either "http://mixi.jp/" or https://mixi.jp/ the window is not shown. Besides, if a user has not set up "easy login" for a feature phone, a message comes up to prompt the user to set up the easy login.

The authorization window shows the list of scopes specified for scope parameter and a user is able to decide if the user consents to authorize the process for the client program.

Upon the user's consent, the access is redirected to the URL which specified for Redirect URL in registering the services, and a code parameter is added on the access as query parameter. Also, the state parameter is included as a query parameter, if you specify the state parameter at calling the page to authorize. Value of the code parameter is Authorization Code issued by mixi Platform.

Redirecting URL becomes as follows:

http://example.com/callback?code=347ab1db9398d60b5ef3515e672d1e&state=5c1b3eea390b53f54ad0975e9a4bbba2

This Authorization Code shall expire in 3 minutes.

How to get Refresh Token and Access Token

The client program is able to get a refresh token and access token by using the Authorization Code. The program should access at "https://secure.mixi-platform.com/2/token" by POST method and the following parameters should be specified in a request body with application/x-www-form-urlencoded format.

ParameterValue
grant_type "authorization_code"
client_id Consumer key
client_secret Consumer secret
code Authorization Code
server_state Value of server_state tied up with session at the redirect after user's authorization.

Whole URL and the request body looks like following:

POST https://secure.mixi-platform.com/2/token
grant_type=authorization_code&client_id=908ed4da74f885a2ab&client_secret=9720b4826e90ad9f053a57500d3a8c697c01d1&code=347ab1db9398d60b5ef3515e672d1e&redirect_uri=http%3A%2F%2Fserver.name%2Fredirect

If each parameter is appropriate, response should be as follows: such response is formatted as application/json

{"refresh_token":"39c5662a2e8b87d41c1eebe79f68af","expires_in":900,"access_token":"c2be2257f3dae3df4efcb010ae6eea","token_type":"Bearer","scope":"r_profile r_voice"}

Each value describes:

ValueDescription
refresh_token Refresh token text string to refresh an access token
expires_in Time when an access token to be expired in second
access_token Access token text string
token_type The kind of token, always the string "Bearer"
scope Authorization scope list, concatenated with space
id_token String including authorized events.
These values will be included only when scope contains "openid".

The access token is expired in 15 minutes. The refresh token may be expired based on a user's authorization.

Life of the access token and/or refresh token is subject to change without prior notice. You should not design any services based on the current expiring period or write hard coding the period on the client program.

When a request parameter is invalid, the response will have one of the following error messages. The format is application/json.

Error messageDescription
{"error":"invalid_grant"} "code", "redirect_uri", or both are invalid.
{"error":"invalid_client"} "client_id", "client_secret" or both are invalid.
{"error":"unsupported_grant_type"} "grant_type" is invalid.

Access to API

The access token enables you to access to various APIs specified as scope in the authorization process. URI for each API is different, while the access token can be used in common. In calling various APIs, the access token should be specified in the Authorization request header.

After "Bearer" and one space, the access token is stated.

For example,

GET /resource HTTP/1.1
Host: api.mixi-platform.com
Authorization: Bearer c2be2257f3dae3df4efcb010ae6eea

In the case, the Authorization request header is not available, the access token can be specified for access_token parameter.

For People AP, that code should be as follows:

http://api.mixi-platform.com/2/people/@me/@self?access_token=c2be2257f3dae3df4efcb010ae6eea

Normally specifying the access token in the Authorization request header is preferable.

Error Message

When the access token is invalid due to the following reasons in accessing to APIs, such call to API fails and error message is sent as a response.

  • The access token has been expired, or:
  • A user doesn't authorize the sufficient scope

In this cases, "WWW-Authenticate" header which shows the error cause is included in the http response header.

HTTP/1.1 401 Authorization Required
...
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired" 

Followings are the value for error parameter:

invalid_request Request is invalid
invalid_token The access token is invalid
insufficient_scope A user doesn't authorize the sufficient scope for the access

If the access token is expired, we return the message "The access token expired" in error_description. You should re-issue it by following the procedure described below. If the access token is invalid, you should redo from Authorization and Authorization Code process.

How to re-issue the access token

The access token is expired only within 15 minutes, and thus accesses to each API would fail if the access token is expired. A client program can gain a new access token by using a refresh token. Refresh token is the value of the refresh_token that is included in issuing the access token.

In order to re-issue the access token, the client program accesses to https://secure.mixi-platform.com/2/token with POST method. In that case, the following parameters have to be described in the request body with application/x-www-form-urlencoded format.

ParameterValue
grant_type "refresh_token"
client_id Consumer key
client_secret Consumer Secret
refresh_token Refresh token text strings

Whole URL and request body should be as follows:

POST https://secure.mixi-platform.com/2/token
grant_type=refresh_token&client_id=908ed4da74f885a2ab&client_secret=9720b4826e90ad9f053a57500d3a8c697c01d1&refresh_token=39c5662a2e8b87d41c1eebe79f68af

If each parameter is appropriate, you can get the following result: 。

{"refresh_token":"39c5662a2e8b87d41c1eebe79f68af","expires_in":900,"access_token":"b1bdf0cd88d4b400dfe785da132a9a","token_type":"Bearer","scope":"r_profile r_voice"} 

Expiring refresh token

Based on the user's authorization and status of accessing APIs, a refresh token is expired. If the refresh token is expired, the following response is sent to you.

HTTP/1.1 401 Authorization Required
Content-Type: application/json
...
{"error":"invalid_grant"}

Expired refresh token would never work. You have to go through Authorization and Authorization Code.

TOP OF THIS PAGE