Kimlik doğrulama

Tüm API istekleri x-api-key header'ı ile kimlik doğrulaması ve x-signature, x-timestamp ve x-nonce header'ları ile HMAC-SHA256 imza doğrulaması gerektirir.

Zorunlu header'lar

Header	Değer	Durum
`x-api-key`	`tq_xxxxx`	Zorunlu
`Content-Type`	`application/json`	Zorunlu
`x-signature`	`HMAC-SHA256 hex`	Zorunlu
`x-timestamp`	`Unix ms (ör: 1708300000000)`	Zorunlu
`x-nonce`	`Rastgele, en az 16 karakter, her istekte yeni (ör: openssl rand -hex 16)`	Zorunlu

İmza formülü

x-signature = HMAC-SHA256(API_SECRET, METHOD:PATH:timestamp:nonce:bodyHash)
PATH, gönderildiği haliyle sorgu dizesiyle birlikte yoldur (örn. /agents?status=active). GET isteklerinde body boş string olarak imzalanır.

API Secret sadece oluşturulduğunda bir kez gösterilir. Güvenli yerde saklayın.

Timestamp toleransı: ±5 dakika. Bu aralık dışındaki istekler reddedilir.

401 mi, 403 mü? 401, bir şeyin eksik ya da eski olduğu anlamına gelir: x-api-key yok ya da SIGNATURE_REQUIRED, TIMESTAMP_REQUIRED, TIMESTAMP_EXPIRED, NONCE_REQUIRED, NONCE_INVALID. 403, kontrol edilip reddedildiği anlamına gelir: SIGNATURE_INVALID (yanlış secret ya da imzaladığınızdan farklı bir yol, sorgu veya gövde), bilinmeyen, iptal edilmiş ya da süresi dolmuş anahtar veya anahtarın IP izin listesi dışındaki bir adres. Gövdedeki error ya da code hangisi olduğunu söyler.

HMAC imzalı istek örneği

const crypto = require('crypto');

const API_KEY    = 'tq_abc123';
const API_SECRET = 'YOUR_API_SECRET';
const BASE_URL   = 'https://api.touchque.com';

function signRequest(method, path, body, timestamp, nonce) {
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const msg = `${method.toUpperCase()}:${path}:${timestamp}:${nonce}:${bodyHash}`;
  return crypto.createHmac('sha256', API_SECRET).update(msg).digest('hex');
}

const body = JSON.stringify({ externalUsername: 'user@company.com' });
const timestamp = Date.now().toString();
const nonce = crypto.randomBytes(16).toString('hex');
const method = 'POST';
const path = '/auth/generate-secret';

const response = await axios.post(`${BASE_URL}${path}`, body, {
  headers: {
    'x-api-key': API_KEY,
    'x-signature': signRequest(method, path, body, timestamp, nonce),
    'x-timestamp': timestamp,
    'x-nonce': nonce,
    'Content-Type': 'application/json',
  }
});

import hmac, hashlib, time, json, secrets

API_KEY    = "tq_abc123"
API_SECRET = "YOUR_API_SECRET"

def sign_request(method, path, body, timestamp, nonce):
    body_hash = hashlib.sha256(body.encode()).hexdigest()
    msg = f"{method.upper()}:{path}:{timestamp}:{nonce}:{body_hash}"
    return hmac.new(API_SECRET.encode(), msg.encode(), hashlib.sha256).hexdigest()

body = json.dumps({"externalUsername": "user@company.com"})
timestamp = str(int(time.time() * 1000))
nonce = secrets.token_hex(16)
method = "POST"
path = "/auth/generate-secret"

headers = {
    "x-api-key": API_KEY,
    "x-signature": sign_request(method, path, body, timestamp, nonce),
    "x-timestamp": timestamp,
    "x-nonce": nonce,
    "Content-Type": "application/json",
}

BODY='{"externalUsername":"user@company.com"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 | awk '{print $2}')
TS=$(date +%s000)
NONCE=$(openssl rand -hex 16)
MSG="POST:/auth/generate-secret:$TS:$NONCE:$BODY_HASH"
SIG=$(echo -n "$MSG" | openssl dgst -sha256 -hmac "YOUR_API_SECRET" | awk '{print $2}')

curl -X POST https://api.touchque.com/auth/generate-secret \\
  -H "x-api-key: tq_abc123" \\
  -H "x-signature: $SIG" \\
  -H "x-timestamp: $TS" \\
  -H "x-nonce: $NONCE" \\
  -H "Content-Type: application/json" \\
  -d "$BODY"