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

Статус API. Tenant API OneKYC находится в стадии бета-тестирования. Эндпоинты, форматы данных и версии API могут быть изменены. Рекомендуется отслеживать обновления документации.

Для выполнения запросов к OneKYC API с серверной стороны требуется аутентификация. Поддерживаются два механизма: HMAC-подпись для межсерверного взаимодействия (Tenant API) и JWT-токен для доступа к сессии верификации (используется страницей верификации при переходе пользователя по ссылке).

HMAC (серверное взаимодействие с OneKYC API)Copy Anchor Link

Запросы с серверной стороны подписываются с использованием алгоритма HMAC-SHA256. Данный механизм обеспечивает подтверждение того, что запрос исходит от авторизованного владельца API-ключа.

Обязательные заголовки:

• Authorization — HMAC-SHA256 Credential={идентификатор_ключа}, Signature={подпись}
• X-Timestamp — текущее время в формате Unix (секунды). Запросы с отклонением времени более 5 минут отклоняются (защита от replay-атак).

Алгоритм формирования подписи:

1. Сформируйте строку для подписи (компоненты разделяются символом переноса строки \n):

   Копировать

   stringToSign = timestamp + "\n" + method + "\n" + path + "\n" + bodyHash

   где:

   • timestamp — значение заголовка X-Timestamp (Unix-время в секундах)
   • method — HTTP-метод прописными буквами (GET, POST, PUT, DELETE и т.д.)
   • path — полный путь запроса с query-параметрами (например, /tenant/v1/kyc/applicants?page=1)
   • bodyHash — SHA256-хеш тела запроса в hex-формате (пустая строка для GET-запросов и запросов без тела)

2. Вычислите HMAC-SHA256 с использованием секрета API-ключа:

   Копировать

   signature = HMAC-SHA256(stringToSign, api_secret)

   Результат кодируется в hex-формат (строка длиной 64 символа).

3. Сформируйте и отправьте запрос с указанными заголовками. Пример эндпоинта для создания ссылки верификации:

curl -X POST 'https://api.onekyc.io/tenant/v1/kyc/verification-links' \  -H 'X-Timestamp: string' \  -H 'Content-Type: application/json' \  -d '{}'

{  "success": true,  "data": {    "created_at": "string",    "delivery_eligible": true,    "expires_at": "string",    "external_reference": "string",    "external_user_id": "string",    "flow_id": "string",    "id": "string",    "link_url": "string",    "locale": "string",    "qr_code_url": "string",    "redirect_url": "string",    "reuse_reason": "external_reference",    "reused": true,    "session_id": "string",    "session_resumable": true,    "session_status": "string",    "short_url": "string",    "status": "string",    "url": "string",    "verification_link": "string",    "verification_url": "string"  }}

Пример реализации (JavaScript / Node.js):

const crypto = require("crypto");

// 1. Вычисление bodyHash (SHA256-хеш тела запроса)
const body = JSON.stringify({ flow_id: "uuid-here" });
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");

// 2. Формирование строки для подписи
const timestamp = Math.floor(Date.now() / 1000).toString();
const method = "POST";
const path = "/tenant/v1/kyc/verification-links";
const stringToSign = `${timestamp}\n${method}\n${path}\n${bodyHash}`;

// 3. Вычисление HMAC-SHA256 подписи
const apiSecret = "your_api_secret_here";
const signature = crypto
  .createHmac("sha256", apiSecret)
  .update(stringToSign)
  .digest("hex");

// 4. Формирование заголовков запроса
const headers = {
  "Content-Type": "application/json",
  "X-Timestamp": timestamp,
  Authorization: `HMAC-SHA256 Credential=kyc_test_<your_key_id>, Signature=${signature}`,
};

Пример реализации (Go):

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "strconv"
    "time"
)

// 1. Вычисление bodyHash (SHA256-хеш тела запроса)
body := map[string]string{"flow_id": "uuid-here"}
bodyBytes, _ := json.Marshal(body)
hash := sha256.Sum256(bodyBytes)
bodyHash := hex.EncodeToString(hash[:])

// 2. Формирование строки для подписи
timestamp := strconv.FormatInt(time.Now().Unix(), 10)
method := "POST"
path := "/tenant/v1/kyc/verification-links"
stringToSign := fmt.Sprintf("%s\n%s\n%s\n%s", timestamp, method, path, bodyHash)

// 3. Вычисление HMAC-SHA256 подписи
apiSecret := "your_api_secret_here"
mac := hmac.New(sha256.New, []byte(apiSecret))
mac.Write([]byte(stringToSign))
signature := hex.EncodeToString(mac.Sum(nil))

// 4. Формирование заголовков запроса
// Authorization: HMAC-SHA256 Credential=kyc_test_<your_key_id>, Signature={signature}
// X-Timestamp: {timestamp}

Секрет API-ключа отображается при создании ключа в административной панели однократно — сохраните его в защищённом хранилище. Секрет должен храниться исключительно на серверной стороне и не передаваться на клиентскую часть приложения.

Формат ключей:

• KYC-ключи: префикс kyc_live_ для продакшен-среды, kyc_test_ для тестовой среды. Обеспечивают доступ к эндпоинтам /tenant/v1/kyc/.
• KYB-ключи: префикс kyb_live_ для продакшен-среды, kyb_test_ для тестовой среды. Обеспечивают доступ исключительно к эндпоинтам /tenant/v1/kyb/.

Секрет ключа имеет префикс sk_. Создание и отзыв ключей осуществляются в разделе API-ключи административной панели.

Тестовый и рабочий режимы:

• Тестовые ключи (kyc_test_*, kyb_test_*) — предназначены для разработки и тестирования. Реальные верификации не выполняются.
• Рабочие ключи (kyc_live_*, kyb_live_*) — предназначены для продакшен-среды. Обрабатывают реальные верификации пользователей.
• Ключи изолированы: тестовые ключи не имеют доступа к данным рабочей среды и наоборот.
• KYC-ключи не могут использоваться для KYB-эндпоинтов и наоборот — сервер возвращает HTTP 403.

Области доступа (scopes): при создании ключа задаются области доступа, определяющие набор доступных операций.

KYC scopes (для ключей kyc_*):

KYB scopes (для ключей kyb_*):

Ручное ревью для интеграторов: Задачи ревью.

Каждый эндпоинт требует соответствующий scope; при недостаточных правах доступа возвращается HTTP 403. Поддерживаются wildcard-scopes: * (полный доступ) или applicants:* (все операции с аппликантами).

JWT (доступ к сессии верификации)Copy Anchor Link

После активации ссылки верификации выдаётся краткосрочный JWT-токен. Данный токен используется страницей верификации OneKYC: при переходе пользователя по ссылке все запросы к API (получение данных сессии, загрузка документов, прохождение шагов) выполняются с заголовком Authorization: Bearer <token>. Срок действия токена задаётся при создании ссылки (например, 600 секунд).

Итог: серверная интеграция использует HMAC-подпись и API-ключ для вызова Tenant API; доступ пользователя к процедуре верификации обеспечивается JWT-токеном, выданным при активации ссылки. Подробное описание эндпоинтов приведено в разделах Сессии и Справочник API (OpenAPI).