Аутентификация

Доступ ко всем защищенным эндпоинтам выполняется по HMAC‑подписи с использованием заголовков:

• X-Public-Key: публичный ключ (идентификатор API‑ключа)
• X-Timestamp: метка времени UNIX в секундах (таймзона UTC +0)
• X-Signature: подпись HMAC‑SHA256

Сервис проверяет наличие заголовков, валидность метки времени и совпадение подписи. В случае успеха запрос авторизуется от имени пользователя, связанного с ключом.

Алгоритм подписи

Подпись формируется от канонической строки из двух значений, разделённых переводом строки \n:

1. X-Public-Key
2. X-Timestamp

Далее вычисляется HMAC_SHA256(stringToSign, secret_key).

Псевдокод:

stringToSign = join("\n", [publicKey, timestamp])
signature = hex(hmac_sha256(stringToSign, secret))

Где secret — секретный API.

Ограничения по времени

Запрос должен быть выполнен в пределах допустимого окна относительно X-Timestamp. При существенном отклонении времени (более 5 минут) сервер вернет ошибку аутентификации.

Пример запроса

curl -X POST \
  https://api.transcription.aiesa.ru/api/v1/transcriptions \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: <PUBLIC_KEY>" \
  -H "X-Timestamp: <UNIX_TIMESTAMP>" \
  -H "X-Signature: <HMAC_HEX>" \
  -d '{
    ... // тело запроса
  }'

Примеры вычисления подписи

PHP

$publicKey = getenv('API_PUBLIC');
$secret = getenv('API_SECRET');
$timestamp = time();

$stringToSign = implode("\n", [
    $publicKey,
    $timestamp,
]);

$signature = hash_hmac('sha256', $stringToSign, $secret);
// Используйте $publicKey, $timestamp, $signature в заголовках

Node.js

const crypto = require('crypto');

const publicKey = process.env.API_PUBLIC;
const secret = process.env.API_SECRET;
const timestamp = Math.floor(Date.now() / 1000);

const stringToSign = [publicKey, String(timestamp)].join('\n');
const signature = crypto
  .createHmac('sha256', secret)
  .update(stringToSign)
  .digest('hex');
// Используйте publicKey, timestamp, signature в заголовках

Python

import os, time, hmac, hashlib

public_key = os.getenv('API_PUBLIC')
secret = os.getenv('API_SECRET').encode('utf-8')
timestamp = str(int(time.time()))

string_to_sign = f"{public_key}\n{timestamp}".encode('utf-8')
signature = hmac.new(secret, string_to_sign, hashlib.sha256).hexdigest()
# Используйте public_key, timestamp, signature в заголовках

Ошибки аутентификации

• 401 Missing authentication headers
• 401 Invalid API key
• 401 Timestamp is too old or too far in the future
• 401 Invalid signature