Request Format

Requests can be sent to the API server using the Proxy model or the Trusted model.

　　Proxy model
　　　　These requests require an access token that corresponds to the opensocial_viewer_id issued by the Gadget Server

　　Trusted model
　　　　These requests are accessible by all applications

Support for these access methods differs for each API. For more information, please see the Reference for each API.

Regardless of the access method, OAuth is used for API Authorization. However, the value of the xoauth_requestor_id that is contained in the OAuth request is different for each model.

For more information about generating the OAuth signature, please see the following topic "Generating the OAuth Signature".

Generating the OAuth Signature

In a request from the game server to the API server, the Authorization header contains an OAuth Signature previously generated by the game server. By verifying this value, the API server can prevent falsification or other kinds of malicious requests and can confirm that the request is a legitimate one from the game server.

Generating the Base String

Generate the Base String according to the following procedure.

1. Prepare values that are needed for Base String generation.

• For the Trusted model (OAuth Consumer Request), oauth_token is not included in the parameters.
  • When oauth_token is not included, the OAuth Service Provider interprets that request as a Consumer Request.
  • For detailed specifications related to an OAuth Consumer Request, please see OAuth Consumer Request 1.0 Draft 1.
• For the Trusted model, specify the application ID for xoauth_requestor_id.

2. Query parameters and other parameters consist of a key and a value in the format key=value. They are sorted in alphabetical order by key and then concatenated with "&".
3. These are URI-escaped and concatenated with "&".

Base String generation example

GET&http%3A%2F%2Fapi.example.com&
foo%3Dbar%26
oauth_consumer_key%3Dabcdefghij1234567890%26
oauth_nonce%3Dabcdefghij1234567890%26
oauth_signature_method%3DHMAC-SHA1%26
oauth_timestamp%3D1234567890%26
oauth_token%3Dabcdefghij1234567890%26
oauth_version%3D1.0%26
xoauth_requestor_id%3D12345

Generating the Signature

The digest value is generated by setting as a key Consumer Secret, which was issued to the base string when the application was registered, and oauth_token_secret from the Authorization header, and concatenating these together with "&". This key is used by the oauth_signature_method algorithm in the Authorization header (currently, HMAC-SHA1). Signature can be generated by further BASE64 encoding this value.

Generating the Authorization Header

The parameters needed in the Authorization header are shown below.

1. URI encode the parameter key and value.
2. Enclose the parameter value in double quotation marks (").
3. Concatenate the parameter key and value with "=".
4. Concatenate individual parameters with commas (,).
5. Add the optional realm parameter.

Authorization Header Generation Example

OAuth realm="", 
oauth_consumer_key="abcdefghij1234567890", 
oauth_nonce="abcdefghij1234567890", 
oauth_signature="X9KBpVUD0W17gNznsd568M9QPUI%3D", 
oauth_signature_method="HMAC-SHA1", 
oauth_timestamp="1234567890", 
oauth_token="abcdefghij1234567890", 
oauth_version="1.0", 
xoauth_requestor_id="12345"

OAuth Request Body Hash (Optional)

When sending a POST or PUT request to the API server, you can calculate a hash value for the Request Body and add that value as a required key for the OAuth signature calculation. For detailed specifications, please see OAuth Request Body Hash 1.0 Draft 4.

When the Request Body is included in the verification, find the HASH value of the Request Body using the same algorithm used for generating the OAuth Signature, then base64 encode that value and include it in the oauth_body_hash parameter.

Reference Links

The OAuth Core 1.0 Protocol draft-hammer-oauth-10
OAuth Core 1.0 Revision A
OAuth Request Body Hash 1.0 Draft 4
OAuth Consumer Request 1.0 Draft 1
RESTful Protocol Specification v0.9

Revision History

• 03/15/2013
  • Document migrated