Let's login user "Bruce Wayne" with password "imbatman"
Your REST API call will have the format of:
Request URL:
POST http://api.stackmob.com/user/accessToken
Request Headers:
Content-Type:application/x-www-form-urlencoded
Accept: application/vnd.stackmob+json; version=0
X-StackMob-API-Key: /* The Public Key*/
X-StackMob-User-Agent: /* your user agent. recommended format: My SDK version # */
Request Body:
username=Bruce%20Wayne&password=imbatman&token_type=mac
You'll be given back the following in the response:
{
"access_token":"vV6xEfVgQZv4ABJ6VZDHlQfCaqKgFZuN",
"mac_key":"okKXxMWOEhnM78Rie02ZjWjP7eQqpp6V",
"mac_algorithm":"hmac-sha-1",
"token_type":"mac",
"expires_in":3600,
"refresh_token":"nZSiH3L5K4febMlELguILucrWpjRud56",
"stackmob":{
"user":{"username":"Bruce Wayne"}
}
}
- You should save the
access_token
andmac_key
somewhere you can refer to for the remainder of the session. - Similarly, because the access token only has one hour to live (as given by
expires_in
), it's recommended you save the expire time somewhere so you can check for the validity of the token. e.g.expireTime = (new Date()).getTime() + 3600 * 1000);
However, this is not required. It's simply so that your client can check to see if the OAuth tokens are still valid by checking the local time against the expire time. - Also for convenience, it's recommended you save the logged in user locally for reference as well:
stackmob['user']['username']
. This is for convenience so that you can display who's logged in.
You can store the above into Local Storage, for instance.
Make API request as you normally would (see REST API docs for StackMob functionality). If the user is logged in, you'll want to include an extra header: Authorization
. Below, we'll go over how to generate the Authorization
string. Example of request to get all books.
Request URL:
http://api.stackmob.com/books
Request Headers:
Accept: application/vnd.stackmob+json; version=0
X-StackMob-API-Key: {The Public Key}
X-StackMob-User-Agent: { your user agent. recommended format: My SDK v.0.5.5}
Authorization:MAC id="vV6xEfVgQZv4ABJ6VZDHlQfCaqKgFZuN",ts="1343427512",nonce="n2468",mac="79js6rr3ynOCyssOHuGpGikfpvs="
StackMob follows the OAuth 2.0 spec for signing Authorization headers as depicted here: http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01
StackMob uses hmac-sha-1 and then base64 encodes the result along with some other items. Below is a JS implementation of
Here's an example of StackMob's JS SDK implementation of the signing: https://gist.github.com/9515a7ecdbb5625b348b
Here's an example of StackMob's iOS SDK implementation of the signing: https://gist.github.com/3410085
Because AJAX can't do cross domain calls, you may be implementing a server proxy, where the AJAX hits your proxy, and then your proxy hits the StackMob servers. The URL would be rewritten to hit api.stackmob.com
instead of the proxy URL, of course.
One way to do this would be simply to initiate a request from your proxy server to StackMob with the same headers and request body as the original request. The Authorization
header will be included in such a request, generated from the client.
You will need additional headers for this to work, however. In the example below, we assume your AJAX is hitting your proxy server at: 127.0.0.1:4567
. Be sure to add the following to the request, appending it to the regular headers of Content-Type
, Authorization
, etc:
Assuming you're calling a GET to http://127.0.0.1:4567/books to get all books, and assuming you're using the access token and mac key from the very top example, this is how you would generate the Authorization header in the JS client side.
var authorizationHeader = call('GET', 'okKXxMWOEhnM78Rie02ZjWjP7eQqpp6V', 'vV6xEfVgQZv4ABJ6VZDHlQfCaqKgFZuN', '127.0.0.1:4567', '/books');
Additional Headers the Proxy Server should add to the request when it makes a request to api.stackmob.com
The proxy server will receive the AJAX request, and in turn will simply make a request with the same headers (original Authorization header too) and URL path, but to http://api.stackmob.com/books
. Be sure to include the headers:
X-Forwarded-For : 127.0.0.1 //your proxy server domain
X-StackMob-Forwarded-Port : 4567 //your proxy server port
X-StackMob-Forwarded-Host : 127.0.0.1 //your proxy server domain
X-Forward-Proto : HTTP //your proxy server scheme
Host : api.stackmob.com
These are needed because StackMob needs to match the authorization signature, and the authorization signature was generated on the client side when the AJAX call was being made to 127.0.0.1:4567/books