Authentication

General

Gillie API authentication works with api keys. Api key information is transmitted with URL parameters:

  • apikey - Public key
  • apisalt - Salt - current unix time as seconds
  • apihash - Hash code - sha256 checksum

How to get your API Key

  1. Login to Gillie
  2. Select Change view and select Administration
  3. Select API Keys from left side menu
  4. Press the +-button for inserting API Key
  5. Enter description and needed permissions (for the test you can give admin permissions)
  6. Save the api key and cut and paste the private and public key and save them to safe location

You can define as many API keys you need. It’s usually a good idea to create separate API keys for every integration/calling system so you can revoke/recreate them as needed.

Each API key has it’s own permissions. You can define the permissions with Gillie’s roles or limit the access by API URL’s. We recommend to use the URL definitions - this way you can control exactly what the API key is allowed to do.

Authentication types

Gillie supports two versions of API key authentication:

  • Authentication with public+private key + salt + hashcode
  • Authentication with plain public key

Authentication with plain public key is more insecure than the hashcode method. Plain public key authentication should be used only when it’s absolutely necessary - like when backend system has a configuration for a fixed URL, or it’s not possible for some reason to make hash key calculation.

Hash code usage is enforced when creating Gillie’s API key.

Authentication with hash code

Authentication with hash code is done with three URL parameters:

  • apikey - Public key
  • apisalt - Salt - current unix time as seconds. Time is checked in backend - must be within 10 minutes of current time
  • apihash - Hash code - sha256 checksum of concatenated string: public key + private key + salt
#! bash
PRIVATEKEY="...your private key..."
PUBLICKEY="...your public key..."
APISALT=`date +%s`
APIHASH=`echo -n "$PRIVATEKEY$PUBLICKEY$APISALT" | shasum -a 256  | cut -d " " -f 1`
curl -v "https://gillie.io/api/customers?apikey=$PUBLICKEY&apisalt=$APISALT&apihash=$APIHASH"

Authentication without hash code

If authentication is allowed for the api key without hash code, then API can be called with plain public key. This is inherently insecure if your public key leaks to non-authorized person in which case you have to delete old api key and recreate new one.

#! bash
curl -v "https://gillie.io/api/customers?apikey=...your public key..."