This API is based on REST principles.
We use HTTP Basic authentication where username is the api key and password is the calculated request signature that changes with every request. The secret should never be sent, instead it's used to generate the request signature. Api key and secret can be generated in our Admin.
The signature is a hex-encoded HMAC-SHA1 hash calculated from the canonical request using provided secret.
Canonical request takes form of {http method} {complete request path} {unix timestamp}
, e.g. GET /v1/some/url?attributes=123&some=aaa 1548240417
PHP example
$time = time(); $method = 'GET'; $path = '/v1/user'; $api = 'https://rest.websupport.sk'; $query = ''; // query part is optional and may be empty $apiKey = 'ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l'; $secret = 'ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq'; $canonicalRequest = sprintf('%s %s %s', $method, $path, $time); $signature = hash_hmac('sha1', $canonicalRequest, $secret); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, sprintf('%s%s%s', $api, $path, $query)); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($ch, CURLOPT_USERPWD, $apiKey.':'.$signature); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Date: ' . gmdate('Ymd\THis\Z', $time), ]); $response = curl_exec($ch); curl_close($ch); echo $response;
Python2 example
import hmac import hashlib import time import requests import base64 from datetime import datetime method = "GET" path = "/v1/user/self" timestamp = int(time.time()) api = "https://rest.websupport.sk" query = "" # query part is optional and may be empty apiKey = "ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l" secret = "ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq" canonicalRequest = "%s %s %s" % (method, path, timestamp) signature = hmac.new(secret, canonicalRequest.encode('utf-8'), hashlib.sha1).hexdigest() headers = { "Content-Type": "application/json", "Accept": "application/json", "Date": datetime.fromtimestamp(timestamp).isoformat() } print requests.get("%s%s%s" % (api, path, query), headers=headers, auth=(apiKey, signature)).content
Python3 example
pip3 install requests
import hmac import hashlib import time import requests import base64 from datetime import datetime, timezone method = "GET" path = "/v1/user/self" timestamp = int(time.time()) api = "https://rest.websupport.sk" query = "" # query part is optional and may be empty apiKey = "ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l" secret = "ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq" canonicalRequest = "%s %s %s" % (method, path, timestamp) signature = hmac.new(bytes(secret, 'UTF-8'), bytes(canonicalRequest, 'UTF-8'), hashlib.sha1).hexdigest() headers = { "Content-Type": "application/json", "Accept": "application/json", "Date": datetime.fromtimestamp(timestamp, timezone.utc).isoformat() } print(requests.get("%s%s%s" % (api, path, query), headers=headers, auth=(apiKey, signature)).content)
PowerShell 7 example
$api_id = "ak48l3h7-ak5d-qn4t-p8gc-b6fs8c31" $api_secret = "ajvkeo3y82ndsu2smvxy3o36496dcascksldncs1" $current_time = Get-Date -UFormat %s $method = 'GET' $api = "https://rest.websupport.sk" $path = "/v1/user/self" # query part is optional and may be empty: $query = "" $canonical_request = "$method $path $current_time" $hmacsha = New-Object System.Security.Cryptography.HMACSHA1 $hmacsha.key = [Text.Encoding]::ASCII.GetBytes($api_secret) $signature_byte = $hmacsha.ComputeHash([Text.Encoding]::ASCII.GetBytes($canonical_request)) $signature = ($signature_byte|ForEach-Object ToString x2) -join '' $base64EncodedString = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(($api_id+":"+$signature))) $Headers = @{ 'Authorization' = "Basic $base64EncodedString" 'Content-Type' = "application/json" 'Accept' = "application/json" 'Date' = (Get-Date $current_time).ToString('yyyy-MM-ddTHH:mm:ss') } $parameters = @{ Uri = "$api$path$query" Headers = $Headers Method = $method } Invoke-RestMethod @parameters
Shell example
#!/bin/bash function hash_hmac { digest="$1" data="$2" key="$3" shift 3 echo -n "$data" | openssl dgst "-$digest" -hmac "$key" "$@" } method="GET" path="/v1/user/self" api="https://rest.websupport.sk" query="" apiKey="ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l" secret="ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq" signature=$(hash_hmac "sha1" "${method} ${path} $(date +%s)" "${secret}") curl "${api}${path}${query}" -u "${apiKey}:$(echo $signature | cut -d " " -f2)" -H "Date: $(date +%Y%m%dT%H%M%SZ --utc)" -H "Accept: application/json" -H "Content-Type: application/json"
Please add Authorization:
header to all requests.
Example: Authorization: Basic aHR0cHdhdGNoOmY=
(last string is base64 encoded version of <apiKey>:<signature>
)
Additionally all request must contain a valid Date
header with the time used for the signature in the ISO8601 basic format, in the GMT timezone.
Connection is encrypted with SSL, so all your requests are safe.
This API is using JSON format in both directions. Please add these two headers to your request:
Content-Type: application/json
Accept: application/json
The communication through API is using UTF-8 encoding.
response
400
{ "code": 400, "message": "This is an example error message!" }
API supports different languages in validation messages. You can change language with header Accept-Language: en_us
. Supported languages are: en_us
, sk
, cs_cz
, hu
.