Skip to main content

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.

Modelxoauth_requestor_id
ProxyValue of opensocial_viewer_id that was passed from the Gadget Server
TrustedApplication 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.
ItemDescription
Request methodHTTP method for sending a request to the API server
API URLRequest URL to the API server (without the query parameters)
Query parametersQuery parameters of the request sent to the API server
ParameterSee the parameters below
ParameterDescriptionSource
oauth_consumer_keyKey for each applicationIssued when the application is registered
oauth_nonceUnique value for each requestGenerated by the game server
oauth_timestampUNIX timestampGenerated by the game server
oauth_tokenAccess tokenValue of oauth_token in the Authorization request header from the Gadget server
oauth_signature_methodSignature methodAlways HMAC-SHA1
oauth_versionOAuth versionAlways 1.0
xoauth_requestor_idID of user executing the applicationValue 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.
  1. 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 "&".
  2. These are URI-escaped and concatenated with "&".
Base String generation example​
ParameterValue
Request methodGET
API URLhttp://app.example.com?foo=bar
oauth_consumer_keyabcdefghij1234567890
oauth_nonceabcdefghij1234567890
oauth_timestamp1234567890
oauth_tokenabcdefghij1234567890
oauth_signature_methodHMAC-SHA1
oauth_version1.0
xoauth_requestor_id12345
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.

References​

OAuth Core 1.0 Revision A
OAuth Request Body Hash 1.0 Draft 4
OAuth Consumer Request 1.0 Draft 1

更新履歴​

  • 2013/03/15
    • document migration