LogoLogo
API Specification
  • Introduction
  • Integration Checklist
  • Common Use Cases
    • Events / Tickets
    • Travel / Accomodation
    • Property / Renters
    • Parcel / Shipping
    • Product / Retail
  • API Authentication
  • Idempotency Keys
  • Rate Limits
  • Purchase Workflow Overview
    • Quote Request for Policies
      • Fast Quote (Optional)
      • Displaying the Quote
      • JS based offer display
    • Payment Process
      • Single Payment
      • Dual Payment
    • Booking
      • Instant Booking
    • Insurance Opt-Out
  • Cancellation Workflow
  • Modification Workflow
  • Renewal Workflow
  • Instalments Workflow
  • Claim
  • Policy Management
  • XCover Quote Package State
  • API Responses
    • Quote/Policy Status
    • Error Management
    • Error Types
  • Data Formats
  • Webhooks
  • Apple Private Relay
  • FAQs
    • Events / Tickets FAQs
Powered by GitBook
On this page
  • Generate HMAC Signature
  • Testing API Keys

Was this helpful?

Export as PDF

API Authentication

PreviousProduct / RetailNextIdempotency Keys

Last updated 1 year ago

Was this helpful?

All HTTP requests sent to the XCover API must be signed with a special signature. The signature must be provided in the Authorization header. In order to generate signature partners need to have a valid API key and a secret signing key. Please note, a new signature must be generated for every request.

Generate HMAC Signature

XCover API uses authentication.

To authenticate API request the client application needs to perform the following steps:

  1. Prepare request data for signing.

  2. Sign data using one of the HMAC algorithms such as SHA1 (dprecated), SHA256 , SHA384 or SHA512 algorithms.

  3. Encode the signature using Base64 encoding.

  4. URL encode the result of the previous step.

  5. Prepare Authorization header containing the Base64 and URL encoded signature string, API Key and the algorithm used, for example hmac-sha512.

Please note the date string to be signed should be in e.g. Thu, 04 Nov 2021 18:07:11 GMT

The date must be padded e.g. 04.

Please note the signature must be a base64 encoded strictly matching RFC 4648. Some programming languages will URL safe base64 encode which will replace the "+" and "/" characters with "-" and "_" respectively. This will cause a "Signature string does not match!" error.

Below you can see an example code implementing these steps, this code can be used as a pre-request script in Postman.

var apiKey = environment.api_key,
    apiSecret = environment.api_secret,
    date = (new Date()).toUTCString(),
    sigContent = 'date: ' + date,
    sig = CryptoJS.HmacSHA512(sigContent, apiSecret).toString(CryptoJS.enc.Base64),
    authHeader = 'Signature keyId="' + apiKey + '",algorithm="hmac-sha512",signature="' + encodeURIComponent(sig) + '"';

pm.environment.set("authHeader", authHeader);  // Authorization header
pm.environment.set("date", date);  // Date header
import requests
# Module defined below
from auth import SignatureAuth

# Prodivded by the assigned Client Solutions Engineer (CSE)
XCOVER_API_KEY = ""
XCOVER_SECRET = ""

def _apply_auth(request):
    request.headers.update(
        SignatureAuth(XCOVER_API_KEY,
                      XCOVER_SECRET).sign()
    )
    return request

session = requests.Session()
request = requests.Request('POST', url, json=payload, headers=headers)
response = session.send(_apply_auth(request.prepare()))

print(response.status_code)
    
# auth.py
"""
Authentication related module.
"""
from __future__ import unicode_literals
​
from base64 import b64encode
from hashlib import sha512
import hmac
from urllib.parse import quote
​
from datetime import datetime
from time import mktime
from wsgiref.handlers import format_date_time
​
def http_date():
    now = datetime.utcnow()
    return format_date_time(mktime(now.timetuple()))
​
​
class SignatureAuth:
    """Class for basic authentication support."""
​
    def __init__(self, key, secret):
        self._key = key
        self._secret = secret
        self._headers = None
​
    def create_signature(self, date):
        raw = 'date: {date}'.format(date=date)
        hashed = hmac.new(self._secret.encode('utf-8'), raw.encode('utf-8'), sha512).digest()
        return quote(b64encode(hashed), safe='')
​
    def build_signature(self, signature, key):
        template = ('Signature keyId="%(key)s",algorithm="hmac-sha512",'
                    'signature="%(signature)s"')
​
        return template % {
            'key': key,
            'signature': signature
        }
​
    def sign(self):
        date = http_date()
        auth = self.build_signature(signature=self.create_signature(date), key=self._key)
​
        return {
            'Date': date,
            'Authorization': auth,
            'X-Api-Key': self._key,
        }
using System;
using System.Web;
using System.Text;
using System.Security.Cryptography;

class Program {
    static void Main(string[] args) {
        String rfc1123DateString = DateTime.Now.ToString("R");
        String apiKey = "";
        String apiSecret = "";
	String signatureContentString = "date: " + rfc1123DateString;
	HMACSHA512 hmacsha512 = new HMACSHA512(Encoding.UTF8.GetBytes(apiSecret));
	byte[] bytes = hmacsha512.ComputeHash(Encoding.UTF8.GetBytes(signatureContentString));
	String signature = Convert.ToBase64String(bytes);
	String authHeader = "Signature keyId=\""+apiKey+"\",algorithm=\"hmac-sha512\",signature=\""+HttpUtility.UrlEncode(signatureString)+"\"";
	return authHeader;
    }
}
require "base64"
require "time"
require 'openssl'
require 'cgi/util'

def auth_header
  rfc1123_date_string = Time.now.httpdate
  api_key = ""
  api_secret = ""
  sig_content = "date: #{rfc1123_date_string}"
  sig = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha512'), api_secret, sig_content)
  encoded_sig = Base64.strict_encode64(sig)
  "Signature keyId=\"#{api_key}\",algorithm=\"hmac-sha512\",signature=\"#{CGI.escape(encoded_sig)}\""
end

Testing API Keys

XCover API offers provides access to staging environment that can be used to test the platform during the integration. To access the sandbox environment partners need to use testing API key that is provided by XCover team.

HMAC-based
RFC 822 Section 5.1 format