Beebotte associates an API & Secret Keys pair to every account. These keys can be used to authenticate access to the API. API & Secret Keys authentication provides full read, write and management access to the account. It uses a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. To authenticate a request, a user first concatenates selected elements of the request to form a string. Then uses his secret key to calculate the HMAC of that string. This process authenticates the user in one hand and signs the request on the second hand.

When Beebotte receives an authenticated request, it fetches the secret key that the user claims to have and uses it in the same way to compute a signature for the message it received. It then compares the signature it calculated against the signature presented by the requester. If the two signatures match, the system concludes that the requester must have access to the secret key and therefore acts with the authority of the principal to whom the key was issued. If the two signatures do not match, the request is dropped and the system responds with an error message.

Example authenticated Beebotte REST request:

POST /v1/data/write/demo/resource1 HTTP/1.1
Content-MD5: 66MMKG87ZakzzoSILd09jg==
Content-Type: application/json
Date: Mon, 07 Oct 2013 14:04:50 GMT
host: beebotte.com
Authorization: 1234567891:HYCb21I1/LhT1vbsXfKVQWpNDQk=

{"data":"37","ts":1400761008646}

The Authentication Header:

Beebotte REST API uses the standard HTTP Authorization header to pass authentication information (The name of the standard header is unfortunate because it carries authentication information, not authorization). Under this authentication scheme, the Authorization header has the following form:

Authorization: ApiKey:Signature

When a user registers to Beebotte, he is issued anAPI Keyand aSecret Key. For request authentication, the API Key element identifies the Secret key that was used to compute the signature and, indirectly, the user making the request.

The Signature element is the RFC 2104HMAC-SHA1 of selected elements from the HTTP request, and so the Signature part of the Authorization header will vary from request to request. If the request signature calculated by the system matches the Signature included with the request, the requester will have demonstrated possession of the secret key. The request will then be processed under the identity, and with the authority, of the user to whom the key was issued.

Authorization = ApiKey + ":" + Signature;

Signature = Base64( HMAC-SHA1( SecretKey, UTF-8-Encoding-Of( StringToSign ) ) );

StringToSign = http verb (upper case) + "\n"
   + Content-MD5 + "\n"
   + Content-type + "\n"
   + Date + "\n"
   + URI