1 - Authenticate
Learn how to authenticate with Hivestack's API
Overview
For our V2 (major version 2) API, we employ an API key authentication strategy. In plain 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:
- Access key
- Secret key - Keep it secret, keep it safe
Obtaining API Credentials
To obtain access to our API, you'll need valid credentials. To get some of these secret little guys, get in touch with a Perion representative.
There are two ways to get in touch with us:
- If you know one of us, get in touch directly. This is the preferred method because it's the quickest way to get you rolling.
- Contact us at [email protected]. We promise we'll get back to you as soon as we can!
Using your API key
Now that you have both your access key and secret key, you'll 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.
Example request header
Here's 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.36Putting it all together
Now you have everything you need to start being productive with the Perion 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
}
]Updated about 1 month ago
