SolarNet API authentication scheme

SolarNet uses a custom HTTP authentication scheme roughly similar to the Amazon S3 web API scheme. Clients of the API must use a security token pair to authenticate each request using a HMAC+SHA1 digest of specific request headers.

Request date

The request must include a HTTP date header, either using the standard HTTP Date header or the custom X-SN-Date header. If X-SN-Date is provided, it will be used in preference to the Date header. The exact date included in HTTP header is included in the message digest so its value must be known by the client. As many browser AJAX fameworks set the Date header automatically, the X-SN-Date can be easier to use.

The value of the request date must match the current date on SolarNetwork at the time the request is made, within a small tolerance value. If the difference between the HTTP header date and the SolarNetwork system date is too large, a HTTP 401 error will be returned with a message along the lines of date skew too large.

Authorization

The request must include a standard HTTP Authorization header using SolarNetworkWS as the authorization scheme. The authorization value is in the form token:hash where token is a SolarUser generated authorization token and hash is the HMAC+SHA1 hash generated from the token secret and message content.

Digest message content

Each request must generate a message out of details included with the request; that message is then used as the input to the HMAC+SHA1 digest algorithm used to authenticate the request. The message consists of the following items, delimited by a newline character such that the last item does not have a newline character added to it (newline character is 0x0A, or \n in most programming languages):

1. HTTP request method, e.g. GET
2. Value of Content-MD5 header (or empty string if none)
3. Value of Content-Type header (or empty string if no content)
4. Request date, from either a X-SN-Date header or a standard Date header, using the pattern EEE, dd MMM yyyy HH:mm:ss zzz in the GMT time zone (the zzz value must be the literal text GMT)
5. Request URI, including sorted request parameters

The request parameters must be included regardless of the HTTP method. For example, if a POST request includes parameters via application/x-www-form-urlencoded encoded body content, those parameters must be included in the request URI.

Putting it all together

Here is an example of a GET request using the SolarNetworkWS authentication scheme:

GET /solaruser/api/v1/sec/instr/viewActive?nodeId=11 HTTP/1.1
Host: data.solarnetwork.net
X-SN-Date: Mon, 23 Sep 2013 03:39:39 GMT
Authorization: SolarNetworkWS a09sjds09wu9wjsd9uy2:IXeexIsjH7beMhxLPU1//1fM9FA=

The raw value of the message content is below (note how lines #2 and #3 are empty):

GET


Mon, 23 Sep 2013 03:39:39 GMT
/solaruser/api/v1/sec/instr/viewActive?nodeId=11

Assuming the message is stored in a variable msg then the Authorization header would be calculated like this, using pseudo code:

token = "a09sjds09wu9wjsd9uy2";
secret = "my secret token";
msg = "...";                             // calculated via rules above
hash = HmacSHA1(msg, secret);
authHeader = "Authorization: SolarNetworkWS " +token + ":" + hash;

API Sampler

See http://data.solarnetwork.net/dev/api/sample.html for a jQuery client implementation of the SolarNetworkWS authentication scheme designed to showcase how the API can be used.