Authentication

The Trustist Ecommerce API uses Hawk Authentication, a message authentication code (MAC) scheme that provides request authentication using a shared secret key.

Overview

Hawk authentication signs each HTTP request with a cryptographic signature, ensuring that:

• Requests are authentic - Only those with valid API keys can make requests
• Data integrity - Request data hasn't been tampered with in transit
• Replay protection - Requests can't be intercepted and re-sent

API Key Structure

Your API credentials consist of two parts, following Hawk nomenclature:

Component	Description	Example
Hawk ID	A GUID that identifies your API key credential (safe to log)	a1b2c3d4-e5f6-7890-abcd-ef1234567890
Hawk Key	Shared secret for signing requests (keep secure!)	sk_live_abc123xyz...

How Hawk Works

For each request, you must include an Authorization header with the following components:

Authorization: Hawk id="HAWK_ID", ts="TIMESTAMP", nonce="RANDOM_STRING", mac="SIGNATURE"

Required Parameters

Parameter	Description
id	Your Hawk ID (GUID)
ts	Unix timestamp (seconds since epoch)
nonce	Random unique string to prevent replay attacks
mac	HMAC-SHA256 signature calculated from request details

Generating the MAC Signature

The MAC is an HMAC-SHA256 hash of a normalized request string. The format is:

hawk.1.header
{timestamp}
{nonce}
{method}
{uri}
{host}
{port}

Note: The last two lines are empty (for hash and ext, which we don't use).

Client Libraries

We recommend using an existing Hawk client library rather than implementing the authentication yourself. Libraries are available for most programming languages:

Node.js / JavaScript

Install the official Hawk package:

npm install @hapi/hawk

Example:

const Hawk = require('@hapi/hawk');
const axios = require('axios');

const credentials = {
    id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    key: 'sk_live_your_secret_key_here',
    algorithm: 'sha256'
};

const url = 'https://api.trustist.com/v1/customers';
const method = 'GET';

// Generate Hawk header
const { header } = Hawk.client.header(url, method, { credentials });

// Make request
const response = await axios.get(url, {
    headers: {
        'Authorization': header
    }
});

console.log(response.data);

C# / .NET

Use our official Trustist Ecommerce SDK:

dotnet add package Trustist.Ecommerce.ClientSdk

Example:

using Trustist.Ecommerce.ClientSdk;

var config = new TrustistEcommerceConfig
{
    ApiKeyId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    ApiKeySecret = "sk_live_your_secret_key_here",
    BaseUrl = "https://api.trustist.com"
};

var client = new TrustistEcommerceClient(config);

// Make authenticated requests
var customers = await client.Customers.ListAsync();

Python

Use the mohawk library:

pip install mohawk

Example:

import requests
from mohawk import Sender

credentials = {
    'id': 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    'key': 'sk_live_your_secret_key_here',
    'algorithm': 'sha256'
}

url = 'https://api.trustist.com/v1/customers'

sender = Sender(
    credentials,
    url,
    'GET',
    content='',
    content_type=''
)

response = requests.get(
    url,
    headers={'Authorization': sender.request_header}
)

print(response.json())

PHP

Use the dflydev/hawk library:

composer require dflydev/hawk

Example:

<?php
require 'vendor/autoload.php';

use Dflydev\Hawk\Client\Client;
use Dflydev\Hawk\Credentials\Credentials;

$credentials = new Credentials(
    'sk_live_your_secret_key_here',
    'sha256',
    'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
);

$client = new Client();

$request = $client->createRequest(
    $credentials,
    'https://api.trustist.com/v1/customers',
    'GET'
);

$ch = curl_init('https://api.trustist.com/v1/customers');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $request->header()->fieldValue()
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

Testing Authentication

Using Postman

Postman has native support for Hawk authentication (official docs):

1. In the Authorization tab, select Hawk Authentication from the dropdown
2. Enter your Hawk Auth ID (your Hawk ID)
3. Enter your Hawk Auth Key (your Hawk Key)
4. Select sha256 as the Algorithm
5. Leave advanced parameters empty (Postman auto-generates them)

Postman will automatically generate the Authorization header with the correct MAC signature.

Alternative: Pre-request Script

If you prefer to use a pre-request script for automation:

const CryptoJS = require('crypto-js');

// Your credentials
const credentials = {
    id: pm.environment.get('TRUSTIST_KEY_ID'),
    key: pm.environment.get('TRUSTIST_SECRET_KEY')
};

const url = pm.request.url.toString();
const method = pm.request.method;
const timestamp = Math.floor(Date.now() / 1000);
const nonce = CryptoJS.lib.WordArray.random(6).toString();

// Parse URL
const urlObj = new URL(url);
const host = urlObj.hostname;
const port = urlObj.port || (urlObj.protocol === 'https:' ? '443' : '80');
const resource = urlObj.pathname + urlObj.search;

// Build normalized string
const normalized = `hawk.1.header\n${timestamp}\n${nonce}\n${method}\n${resource}\n${host}\n${port}\n\n\n`;

// Calculate MAC
const mac = CryptoJS.HmacSHA256(normalized, credentials.key).toString(CryptoJS.enc.Base64);

// Set header
const header = `Hawk id="${credentials.id}", ts="${timestamp}", nonce="${nonce}", mac="${mac}"`;
pm.request.headers.add({ key: 'Authorization', value: header });

Using cURL

While you can manually calculate the Hawk header, we recommend using a client library. However, for testing:

# First, generate the header using a script or library
# Then use it with curl:

curl -X GET "https://api.trustist.com/v1/customers" \
  -H "Authorization: Hawk id=\"YOUR_ID\", ts=\"1234567890\", nonce=\"abc123\", mac=\"CALCULATED_MAC\""

Common Authentication Errors

401 Unauthorized

Causes:

• Missing Authorization header
• Invalid API key ID
• Incorrect signature calculation
• Timestamp too far from server time (>60 seconds)

Solutions:

• Verify your API key ID and secret are correct
• Ensure your system clock is synchronized (use NTP)
• Check that you're using the correct HMAC algorithm (SHA-256)
• Verify the normalized request string format

403 Forbidden

Causes:

• Your API key lacks the required permission for this endpoint
• The tenant associated with your key doesn't have access to this resource

Solutions:

• Check your API key permissions in the TrustistTransfer app
• Request additional permissions if needed
• Verify you're accessing resources that belong to your tenant

Security Best Practices

Next Steps

Now that you understand authentication:

1. Follow the Quick Start guide to make your first authenticated request
2. Browse the API Reference to see all available endpoints
3. Set up the sandbox environment for testing