1 - Authenticate

Overview

For our V2 (major version 2) API, we employ an API key authentication strategy. What that means in english: for each request you must provide a a key in either the request header, or as a parameter in the query string. Your key consists of 2 components:

1. Access key
2. Secret key - Keep it secret, keep it safe

Obtaining API Credentials

To obtain access to our API, you will need valid credentials. To get some of these secret little guys, get in touch with a Hivestack representative.

There are a few ways to get in touch with us:

1. If you know one of us, get in touch directly. This is preferred method because it is the quickest way to get you rolling.
2. Contact us at [email protected]. We promise we'll get back to you as soon as we can!

Using your API key

So you have an access key and a secret key, now what? You need to send it along with each request. You do this by setting the hs-auth header to apikey <access_key>:<secret_key> (replacing <access_key> and <secret_key> with your keys).

Note: The colon ":" separating your access key and secret keys is required. Alternatively you may use a pipe "|" instead of a colon if it makes your life any easier for some, possibly weird, reason.

Example request header

An exhaustive example of the headers sent in a typical request. A lot of what you see below is generated for you by your HTTP client.

:authority:privateurl.com
:method:GET
:path:/api/v2/networks/?$count=true&$top=10&$skip=0
:scheme:https
accept:application/json, text/plain, */*
accept-encoding:gzip, deflate, br
accept-language:en-US,en;q=0.8
hs-auth:apikey access_key:secret_key
cache-control:no-cache
pragma:no-cache
referer:https://privateurl.com/
user-agent:Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36

Putting it all together

Now you have everything you need to start being productive with the Hivestack API! Let's put it all together in a sample request

• URL

  https://privateurl.com/api/v2/networks

• Method:

  GET

• Headers:

:authority:privateurl.com
:method:GET
:path:/api/v2/networks
:scheme:https
accept:application/json, text/plain, */*
accept-encoding:gzip, deflate, br
accept-language:en-US,en;q=0.8
hs-auth:apikey access_key:secret_key
cache-control:no-cache
pragma:no-cache
referer:https://privateurl.com/
user-agent:Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36

• Response:

[
  {
        "active": true,
        "code": "DIGI",
        "created_on_utc": "2019-01-01T15:00:00",
        "modified_on_utc": "2019-01-01T15:00:00",
        "name": "Digital Billboards",
        "network_id": 1337,
        "owner_id": 999
    }
]