Keyft API Documentation

API Request Authentication

All outbound requests from external clients or edge workers to our backend cluster must include your production API Key (kft_live_...) within the HTTP header using the Bearer Token authorization scheme.

HTTP Header Specification

Header Name: Authorization
Header Format: Bearer kft_live_YOUR_API_KEY
Content-Type: application/json

1. cURL Implementation

Bash / cURL

curl -X POST "/api/client/settings" \
  -H "Authorization: Bearer kft_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vpn_check_enabled": 1,
    "gps_check_enabled": 1,
    "tamper_check_enabled": 1,
    "max_gps_accuracy": 50,
    "vpn_action": "BLOCKED",
    "gps_action": "CHALLENGED",
    "tamper_action": "BLOCKED"
  }'

2. Client-Side / Edge Worker Implementation (JavaScript Fetch)

JavaScript (ES6)

const apiKey = 'kft_live_YOUR_SECRET_KEY';

const response = await fetch('/api/client/runtime-health', {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
    }
});

const result = await response.json();
console.log('Runtime Health Status:', result);

Webhook Integrity Verification

To prevent Man-in-the-Middle (MITM) attacks and third-party payload spoofing (including requests destined for SAP Enterprise Gateways or custom middleware listeners), every outbound webhook event attaches a cryptographic HMAC-SHA256 signature to the X-KeyFT-Signature HTTP header.

Your receiving endpoint must verify this digital signature using your unique Signing Secret (whsec_...) issued during webhook endpoint creation.

Verification Workflow

1. Capture incoming request body data as an unparsed raw string or byte buffer.
2. Extract the signature hash string from the X-KeyFT-Signature request header.
3. Compute the expected HMAC-SHA256 signature using your raw payload buffer and your whsec_... secret.
4. Perform a constant-time comparison between the calculated hash and the header signature.

Receiver Example (Node.js + Express)

Node.js (Express Server)

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use('/api/webhook-receiver', express.raw({ type: 'application/json' }));

app.post('/api/webhook-receiver', (req, res) => {
    const SIGNING_SECRET = 'whsec_YOUR_WEBHOOK_SIGNING_SECRET';
    const clientSignature = req.headers['x-keyft-signature'];
    
    if (!clientSignature) {
        return res.status(401).json({ error: 'Missing X-KeyFT-Signature header' });
    }

    const calculatedHash = crypto
        .createHmac('sha256', SIGNING_SECRET)
        .update(req.body)
        .digest('hex');

    const isValid = crypto.timingSafeEqual(
        Buffer.from(clientSignature, 'utf-8'),
        Buffer.from(calculatedHash, 'utf-8')
    );

    if (!isValid) {
        return res.status(403).json({ error: 'Invalid HMAC signature verification failed' });
    }

    const payload = JSON.parse(req.body.toString());
    console.log('Webhook Event Verified & Received:', payload);

    res.status(200).json({ success: true, status: 'DELIVERED' });
});

app.listen(3000, () => console.log('Webhook Listener server running on port 3000'));