Signing Request
There are 3 methods to sign a RESTful API request. Depending on the API that you are calling, you can sign your request by one of the following methods. You will find which method to use in each detail page of the API Reference.
-
Client Only Signing (sometimes called 2-legged Authorization or Trusted model)
In this method, a request is signed using only the consumer secret of the app. This method is used when either an access token is not available, or the operation is not bound to a specific user, such as sending remote notification to all users. -
3-legged Authorization Signing (sometimes called Proxy model)
This is the full OAuth 3-legged authorization. The request is signed using both the consumer secret and access token secret. This method is used in requesting access token and most Social API requests. -
OAuth2 Authorization
This does not require any signing but instead require communication over HTTPS. The request simply needs to bear the oauth2_token in its HTTP Authorization header. This is only used for the Bank API, except for the Simplified and Traditional Chinese platforms.info
It is possible that the same API accepts both Client Only Signing and 3-legged Authorization Signing. Depending on the context, these APIs behave differently when different signing methods are used. For more information read the detail page of each API. :::
Below we will look at how to sign a request with each of above methods.
Client Only Signing
First we create the so-called Base String following below steps, then we use the HMAC-SHA1 hashing algorithm to create the signature string of the Base String using the consumer secret for your application. Then, we construct the final Authorization header that must be included in the request's HTTP header to make a successful call.
Client Only Signing and 3-legged Authorization Signing are basically the same, except that 3-legged Authorization Signing includes access token string into OAuth parameters, and uses both consumer secret and access token secret while signing the base string.
Step 1. Create the Base String
-
Construct the OAuth parameters string by:
-
Sort the following parameters by name alphabetically.
-
URLEncode (based on RFC 3986) the parameter names and values.
-
Join name and value with "=".
-
Join name/value pairs with "&".
Parameter Description Value oauth_callback Redirect URI Only "oob" (Out-of-band) is accepted. oauth_consumer_key The Consumer Key Available on Mobage Developers portal, unique to each application. oauth_nonce Number used only once You can freely generate this. Must be unique for each request. oauth_signature_method Hash method Only "HMAC-SHA1" is accepted. oauth_timestamp UNIX timestamp Generate this on the game server. oauth_verifier The verifier returned by Mobage SDK Only required for /request_token. oauth_version OAuth version Only "1.0" is accepted. Query parameters Query parameters All additional query parameters. For example, in the case of "param1=value1¶m2=value2", the parameters are "param1=value1", "param2=value2".
-
-
URLEncode (based on RFC 3986) the following parameters.
Parameter Description Request Method HTTP Method to the API Server (i.e. GET, POST, PUT, DELETE) API URL URL to the API Server (exclude query parameters) OAuth Parameters A string constructed in the previous step. -
Join the above 3 encoded parameters in previous step with "&". The output string in this step is called the "base string".
Step 2. Generate oauth_signature
- Build a secret string by joining the Consumer Secret and an empty string with "&".
- Pass the base string and secret string to the HMAC-SHA1 hashing algorithm.
- The output of HMAC-SHA1 hashing algorithm is binary data. Use Base64 encode to produce the final signature string.
Step 3. Construct the Authorization Header
-
URLEncode (based on RFC 3986) the names and values of the following parameters.
-
Double quote the value, join name and value with "=".
-
Join name/value pairs with ",".
-
Add realm parameter as an option.
-
Add "OAuth " (including the space at the end) to the beginning of the string.
Parameter Value oauth_callback Only "oob" (Out-of-band) is accepted oauth_consumer_key The Consumer Key available on Mobage Developers portal, unique to each application. oauth_nonce You can freely generate this. Must be unique for each request. oauth_signature The output of above Step2. oauth_signature_method only "HMAC-SHA1" is accepted. oauth_timestamp Generate this on the game server. oauth_verifier The verifier returned by Mobage SDK, only required for /request_token. oauth_version Only "1.0" is accepted.
An Authorization Header example
The parameters for base string are as follows:
| Parameter | Value |
|---|---|
| Request Method | POST |
| API URL | https://ssl.sb.sp.mbga-platform.jp/social/api/oauth/v2.01/request\_temporary\_credential |
| oauth_callback | oob |
| oauth_consumer_key | c8bb6e04c60b9f6c0063 |
| oauth_nonce | fa894d8b9be49cd5191ee126b02e4171 |
| oauth_timestamp | 1380117217 |
| oauth_signature_method | HMAC-SHA1 |
| oauth_version | 1.0 |
The base string generated based on above sample:
Change of lines are inserted for reading purpose, the base string should be one continuous string without spaces or line breaks.
POST&
https%3A%2F%2Fssl.sb.sp.mbga-platform.jp%2Fsocial%2Fapi%2Foauth%2Fv2.01%2Frequest_temporary_credential&
oauth_callback%3Doob%26
oauth_consumer_key%3Dc8bb6e04c60b9f6c0063%26
oauth_nonce%3Dfa894d8b9be49cd5191ee126b02e4171%26
oauth_signature_method%3DHMAC-SHA1%26
oauth_timestamp%3D1380117217%26
oauth_version%3D1.0
The signature string generated:
Ea2bmHas4x4Cd4CCR7ZrWn2gZMM=
The Authorization header:
Authorization: OAuth oauth_version="1.0",oauth_nonce="fa894d8b9be49cd5191ee126b02e4171",oauth_timestamp="1380117217",oauth_consumer_key="c8bb6e04c60b9f6c0063",oauth_callback="oob",oauth_signature_method="HMAC-SHA1",oauth_signature="Ea2bmHas4x4Cd4CCR7ZrWn2gZMM%3D"
For more examples, see the examples on each API detail page.
3-legged Authorization Signing
First we create the so-called Base String following below steps, then we use the HMAC-SHA1 hashing algorithm to create the signature string of the Base String using the consumer secret for your application and access token secret you received from the platform. Then, we construct the final Authorization header that must be included in the request's HTTP header to make a successful call.
Client Only Signing and 3-legged Authorization Signing are basically the same, except that 3-legged Authorization Signing includes access token string into OAuth parameters, and uses both consumer secret and access token secret while signing the base string.
Step 1. Create the Base String
-
Construct the OAuth parameters string by:
-
Sort the following parameters by name alphabetically.
-
URLEncode (based on RFC 3986) the parameter names and values.
-
Join name and value with "=".
-
Join name/value pairs with "&".
Parameter Description Value oauth_consumer_key The Consumer Key Available on Mobage Developers portal, unique to each application. oauth_nonce Number used only once You can freely generate this. Must be unique for each request. oauth_signature_method Hash method Only "HMAC-SHA1" is accepted. oauth_timestamp UNIX timestamp Generate this on the game server. oauth_token OAuth access token Access token that you received from the platform. oauth_version OAuth version Only "1.0" is accepted. Query parameters Query parameters All additional query parameters. For example, in the case of "param1=value1¶m2=value2", the parameters are "param1=value1", "param2=value2".
-
-
URLEncode (based on RFC 3986) the following parameters.
Parameter Description Request Method HTTP Method to the API Server (i.e. GET, POST, PUT, DELETE) API URL URL to the API Server (exclude query parameters) OAuth Parameters A string constructed in the previous step. -
Join the above 3 encoded parameters in previous step with "&". The output string in this step is called the "base string".
Step 2. Generate oauth_signature
- Build a secret by joining the Consumer Secret and the Token Secret (obtained from the token credential) with "&".
- Pass the base string and secret string to the HMAC-SHA1 hashing algorithm.
- The output of HMAC-SHA1 hashing algorithm is binary data. Use Base64 encode to produce the final signature string.
Step 3. Construct the Authorization Header
-
URLEncode (based on RFC 3986) the names and values of the following parameters.
-
Double quote the value, join name and value with "=".
-
Join name/value pairs with ",".
-
Add realm parameter as an option.
-
Add "OAuth " (including the space at the end) to the beginning of the string.
Parameter Value oauth_consumer_key The Consumer Key available on Mobage Developers portal, unique to each application. oauth_nonce You can freely generate this. Must be unique for each request. oauth_signature The output of above Step2. oauth_signature_method only "HMAC-SHA1" is accepted. oauth_timestamp Generate this on the game server. oauth_token Access token that you received from the platform. oauth_version Only "1.0" is accepted.
An Authorization Header example
The parameters for base string are as follows:
| Parameter | Value |
|---|---|
| Request Method | GET |
| API URL | http://sb.sp.mbga-platform.jp/social/api/restful/v2/social/api/restful/v2/people/@me/@self |
| oauth_consumer_key | c8bb6e04c60b9f6c0063 |
| oauth_nonce | d224def28b2da93532f68f909e7c4680 |
| oauth_signature_method | HMAC-SHA1 |
| oauth_timestamp | 1380204695 |
| oauth_token | sp_client_id:c2585ae2691471227feadcbc469dfbf8 |
| oauth_version | 1.0 |
| fields | nickname |
The base string generated based on above sample:
Change of lines are inserted for reading purpose, the base string should be one continuous string without spaces or line breaks.
GET&
http%3A%2F%2Fsb.sp.mbga-platform.jp%2Fsocial%2Fapi%2Frestful%2Fv2%2Fpeople%2F%40me%2F%40self&
fields%3Dnickname%26
oauth_consumer_key%3Dc8bb6e04c60b9f6c0063%26
oauth_nonce%3Dd224def28b2da93532f68f909e7c4680%26
oauth_signature_method%3DHMAC-SHA1%26
oauth_timestamp%3D1380204695%26
oauth_token%3Dsp_client_id%253Ac2585ae2691471227feadcbc469dfbf8%26
oauth_version%3D1.0
The signature string generated:
CNLj8zRoeT/f/koOMa/5ucfPL2M=
The Authorization header:
Authorization: OAuth oauth_version="1.0",oauth_nonce="d224def28b2da93532f68f909e7c4680",oauth_timestamp="1380204695",oauth_consumer_key="c8bb6e04c60b9f6c0063",oauth_token="sp_client_id%3Ac2585ae2691471227feadcbc469dfbf8",oauth_signature_method="HMAC-SHA1",oauth_signature="CNLj8zRoeT%2Ff%2FkoOMa%2F5ucfPL2M%3D"
For more examples, see the examples on each API detail page.
OAuth2 Authorization
This is the easiest authorization method of all above. Simple use the oauth2_token string you received from platform as a bearer token in the HTTP Authorization header and you are done.
The Authorization header:
Authorization: bearer 369dfdce13174503a609cce70767c188
For more examples, see the examples on each API detail page.