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

HMAC-подпись и заголовки для доступа к защищённым эндпоинтам

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

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

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

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

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

X-Public-Key
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 '{
    ... // тело запроса
  }'

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

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 в заголовках

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

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