Authentication

Overview

The ShelterBuddy API enforces authentication for all API calls. There are two methods a consumer of the API can choose from to authenticate their call. The first method uses the traditional cookie approach. This method is very similar to how a normal website controls authentication, whereby upon successful authentication, a cookie is returned and each subsequent request the cookie is sent. The other method of authentication supported by the API is a custom header/value pair. With this method the caller adds to their request header the issued token set against the header key of `sb-auth-token`.

Maintaining authentication

By default an authentication token/cookie is valid for 2 hours. In addition, each successful request to the API will include in the response a new authentication token/cookie. Simply, the API will slide the expiry of a valid authenticated call.

Approach one: Keeping token/cookie for the duration of two hours.

Pros: Easy

Cons: Need to track time, Logic to handle token/cookie time out.

Approach two: Update token/cookie after each call.

Pros: Authentication will slide

Cons: Need to track cookie, Logic to handle token/cookie time out.

Some REST clients will automatically track cookies with minimal or even without any custom logic required

How to authenticate

You will be issued a username and password. These credentials can be used to authenticate via the API endpoint /api/v2/authenticate. A successful call to this API will result with being issued a cookie and token.

Below is a sample HTTP request to authenticate

HTTP Request (RAW)

GET http://shelterbuddy-development/api/v2/authenticate?username=*******&password=**** HTTP/1.1
Content-Type: application/json
Accept: application/json, application/xml, text/json, text/x-json, text/javascript, text/xml
User-Agent: RestSharp 104.1.0.0
Host: shelterbuddy-development-public
Accept-Encoding: gzip, deflate
Connection: Keep-Alive

The response to request. Take note that both a cookie is set and a token returned.

HTTP Response (RAW)

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 706
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.30319
Set-Cookie: .ASPXAUTH=3CD93F4BE83**********; expires=Sat, 19-Oct-2013 02:46:27 GMT; path=/; HttpOnly
X-Powered-By: ASP.NET
Date: Sat, 19 Oct 2013 00:46:27 GMT
"3CD93F4BE83**********"

Code examples

Header based authentication

	var client = new RestClient("http://dev.adoptapet.com.au/api/v2/");
	client.AddDefaultHeader("content-type", "application/json");
	
	var request = new RestRequest("authenticate", Method.GET);
	request.AddQueryParameter("username", "username");
	request.AddQueryParameter("password", "password");
	var result = client.Execute(request);
	var token = (string)JsonConvert.DeserializeObject(result.Content);
	
	client.AddDefaultHeader("sb-auth-token", token);
	
	request = new RestRequest("animals?animalStatusId={id}", Method.GET);
	request.AddUrlSegment("id", "3");
	
	result = client.Execute(request);