Authentication

All requests to the API must be authenticated by either using an API key or having a valid authentication cookie sent with the request.

Table of Contents #

Authenticating requests using API key #

Requests using an API key must provide both an API key, and an API call digest based on a shared secret.

Please refer to Silobreaker API samples on GitHub for authentication samples in several languages. The Node repository contains convenient commands for generating valid digested api links.

The API key is passed using the apiKey parameter on the URL. The digest is provided by adding the parameter digest. The digest is calculated using a shared secret key that is provided when the apiKey is acquired.

Digest definition

A BASE64-encoded HMAC-SHA1-hash of the concatenation of

Example GET request in pseudo-code

Key = "MySharedKey"
UTF8Key = GetUTF8Bytes(Key)

// This is a HTTP GET request
Message = "GET https://api.silobreaker.com/search/documents/Sweden"

HashInput = GetUTF8Bytes(Message)

// Will output YZHTB5EvNKnLhmpyroyGyq71EmQ=
Signature = Base64(HMAC-SHA1(HashInput, UTF8Key));

The final GET request will look like:

https://api.silobreaker.com/search/documents/Sweden?apiKey=MyApiKey&digest=YZHTB5EvNKnLhmpyroyGyq71EmQ%3D

Example POST request in pseudo-code

Key = "MySharedKey"
UTF8Key = GetUTF8Bytes(Key)

// This is a HTTP POST request
Message = "POST https://api.silobreaker.com/search/documents/Sweden"
RequestBody = '{"id": "example"}'

HashInput = Concat(GetUTF8Bytes(Message), GetBytes(RequestBody))

// Will output yuoW8y5jWb6EG2VQAnD9j4QPmiA=
Signature = Base64(HMAC-SHA1(HashInput, UTF8Key));

The final POST request url will look like:

https://api.silobreaker.com/search/documents/Sweden?apiKey=MyApiKey&digest=yuoW8y5jWb6EG2VQAnD9j4QPmiA%3D

Don't forget to urlencode the digest since base64 can contain +

Javascript/Node example

Computing a full digested URI for a GET request in Javascript/Node looks like this:

var crypto  = require('crypto');

var baseUrl = 'https://api.silobreaker.com';
var verb = 'GET';
var call = '/documents?q=list:Attack+Types';

var hmac = crypto.createHmac('sha1', keys.SharedKey);
hmac.setEncoding('base64');
hmac.write(verb + ' ' + baseUrl + call);
hmac.end();
var hash = hmac.read();    

var digestUri = baseUrl + call + '&apiKey=' + keys.ApiKey + '&digest=' + uncodeURIComponent(digest);

Authenticating using authentication cookie #

For building browser-based clients, the Silobreaker API provides cookie-based authentication.

An authentication cookie is requested using the /login endpoint, and then passed with every consecutive request.

POST /v1/login/ #

Sets a session cookie which authenticates further calls to the API.

The login endpoint will return with Status: Success or Delay. The success-Status will include a CookieName property. The delay state will include NextLoginDelayInSeconds which indicates how long you must wait before the next login attempt. If you login before the delay time it'll respond with a new delay time.

Request

POST /v1/login/

{ 
    "Username": "YOUR_USERNAME",
    "Password": "YOUR_PASSWORD"
}

Response

An example JSON object if you logged in successfully

{
  "CookieName": "COOKIENAME",
  "Status": "Success"
}

An example JSON object if you failed to login

{
  "Status": "Delay",
  "NextLoginDelayInSeconds": 10
}

GET /v1/logout, POST /v1/logout #

Logs the current user out.

The /logout endpoint clears the authentication cookie.

Note: This endpoint will result in a logout if and only if a session cookie was used and the request is made using a browser.

The endpoint will return with Status: Logged out or No active session found. If there was a user logged in and it successfully logged out status will be Logged out otherwise No active session found.

Request

GET /v1/logout
POST /v1/logout

Response

A report object.

{
  "Status": "Logged out"
}

GET /v1/loginstatus, POST /v1/loginstatus #

Checks the login status.

To find out the status of the current session POST or GET to this endpoint. It will return with Status: authenticated or unauthenticated.

Request

GET /v1/loginstatus
POST /v1/loginstatus

Response

A report object.

{
  "Status": "authenticated"
}

POST /v1/changepassword #

Changes the users password.

This endpoint only supports POST and requires the user to send the current password and the new password.

It can respond with one of the following status:

Request

POST /v1/changepassword
{
    "Password": "CURRENT_PASSWORD",
    "NewPassword": "NEW_PASSWORD"
}

Response

A status object.

{
  "Status": "Success"
}

Documentation generated by mdoc.