Request from Game Server to API Server

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.

Model

xoauth_requestor_id

Proxy

Value of opensocial_viewer_id that was passed from the Gadget Server

Trusted

Application ID

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.

Item

Description

Request method

HTTP method for sending a request to the API server

API URL

Request URL to the API server (without the query parameters)

Query parameters

Query parameters of the request sent to the API server

Parameter

See the parameters below

Parameter

Description

Source

oauth_consumer_key

Key for each application

Issued when the application is registered

oauth_nonce

Unique value for each request

Generated by the game server

oauth_timestamp

UNIX timestamp

Generated by the game server

oauth_token

Access token

Value of oauth_token in the Authorization request header from the Gadget server

oauth_signature_method

Signature method

Always HMAC-SHA1

oauth_version

OAuth version

Always 1.0

xoauth_requestor_id

ID of user executing the application

Value of the query parameter opensocial_viewer_id from the Gadget server

  • 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

Parameter

Value

Request method

GET

API URL

http://app.example.com?foo=bar

oauth_consumer_key

abcdefghij1234567890

oauth_nonce

abcdefghij1234567890

oauth_timestamp

1234567890

oauth_token

abcdefghij1234567890

oauth_signature_method

HMAC-SHA1

oauth_version

1.0

xoauth_requestor_id

12345

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.

Parameter

oauth_consumer_key

oauth_nonce

oauth_signature

oauth_signature_method

oauth_timestamp

oauth_token

oauth_version

xoauth_requestor_id

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

PREVIOUS

Request from Gadget Server to Game Server

NEXT

Response from API Server to Game Server