Signing API Payloads

---

Overview

To ensure the security and integrity of API requests, all requests to Tylt must be signed using your API Secret Key. Each request includes a signature generated using HMAC-SHA256, allowing Tylt to verify:

• The authenticity of the request

• That the payload has not been tampered with

---

How Signing Works

1. Prepare the request payload

2. Convert the payload into a string

3. Generate a signature using HMAC-SHA256 with your API Secret Key

4. Include the signature in the request headers

---

Signature Function

const createSignature = (secret, data) => {
    return crypto.createHmac('sha256', secret)
                 .update(data)
                 .digest('hex');
};

---

Signing a POST Request

For POST requests:

• Convert the request body to a JSON string

• Use the exact same string for:

  • request body

  • signature generation

const sendPostRequest = async (url, body) => {
    const raw = JSON.stringify(body);
    const signature = createSignature(apiSecret, raw);
    const headers = {
        "X-TLP-APIKEY": apiKey,
        "X-TLP-SIGNATURE": signature
    };
    const response = await axios.post(url, body, { headers });
    return response.data;
};

---

Signing a GET Request

For GET requests:

• Convert query parameters into a query string

• Use the same query string for signature generation

const sendGetRequest = async (url, params) => {
    const raw = new URLSearchParams(params).toString();
    const signature = createSignature(apiSecret, JSON.stringify(params));
    const headers = {
        "X-TLP-APIKEY": apiKey,
        "X-TLP-SIGNATURE": signature
    };
    const response = await axios.get(`${url}?${raw}`, { headers });
    return response.data;
};

---

Headers

All requests must include:

Header	Description
X-TLP-APIKEY	Your API Key
X-TLP-SIGNATURE	HMAC-SHA256 signature of the request

---

Important Rules

• The string used for signature must exactly match the payload sent

• Any difference in formatting, spacing, or encoding will result in signature mismatch

• Always generate signatures on the server side only

• Never expose your API Secret Key in frontend applications

---

Security Best Practices

• Store API credentials in a secure environment (e.g., secrets manager)

• Rotate keys immediately if compromised

• Restrict API usage to trusted backend systems

---

Example Codes

Here’s how you can sign requests using different programming languages:

Common

// Common function to create HMAC SHA-256 signature
const createSignature = (secret, data) => {
    return crypto.createHmac('sha256', secret)
                 .update(data)
                 .digest('hex');
};

Node JS

Python

JavaScript

Important Considerations

• Keep Your Keys Secure: Always use environment variables or secure storage for sensitive information like your API Secret Key.

• Regenerate Keys if Compromised: If your API keys are exposed or compromised, regenerate them immediately and update your secure storage.