# Аутентификация > **Статус API.** Tenant API OneKYC находится в стадии бета-тестирования. Эндпоинты, форматы данных и версии API могут быть изменены. Рекомендуется отслеживать обновления документации. Для выполнения запросов к OneKYC API с серверной стороны требуется аутентификация. Поддерживаются два механизма: HMAC-подпись для межсерверного взаимодействия (Tenant API) и JWT-токен для доступа к сессии верификации (используется страницей верификации при переходе пользователя по ссылке). ## HMAC (серверное взаимодействие с OneKYC API) [#hmac-серверное-взаимодействие-с-name-api] Запросы с серверной стороны подписываются с использованием алгоритма 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. Сформируйте и отправьте запрос с указанными заголовками. Пример эндпоинта для создания ссылки верификации: API operations: - `POST /v1/kyc/verification-links` **Пример реализации (JavaScript / Node.js):** ```javascript 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_, Signature=${signature}`, }; ``` **Пример реализации (Go):** ```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_, 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_*`): | Scope | Описание | | -------------------- | ------------------------------------ | | `applicants:read` | Чтение данных аппликантов | | `applicants:write` | Изменение и удаление аппликантов | | `sessions:create` | Создание сессий верификации, а также создание, пакетное создание и отзыв KYC-ссылок | | `verifications:read` | Чтение результатов верификации и AML | | `documents:read` | Чтение документов | | `media:read` | Чтение медиафайлов | | `webhooks:read` | Чтение конфигурации вебхуков | | `webhooks:write` | Управление вебхуками | | `metrics:read` | Чтение метрик и аналитики | | `audit:read` | Чтение журнала аудита | | `verification-links:read` | Чтение ссылок верификации | | `documents:upload` | Загрузка документов | | `reviews:read` | Чтение очереди ручного ревью, задач, комментариев и причин отклонения | | `reviews:write` | Assign, решения, комментарии, приоритет и resubmit для KYC review tasks | **KYB scopes** (для ключей `kyb_*`): | Scope | Описание | | ------------------------------ | ---------------------------------------------- | | `businesses:read` | Чтение данных компаний | | `businesses:write` | Изменение данных компаний | | `kyb.sessions:read` | Чтение KYB-сессий | | `kyb.verification-links:read` | Чтение ссылок верификации KYB | | `kyb.verification-links:write` | Создание и управление ссылками верификации KYB | | `kyb.documents:read` | Чтение документов KYB | | `kyb.media:read` | Чтение медиафайлов KYB (также нужен для URL документов в ревью) | | `kyb.webhooks:read` | Чтение конфигурации вебхуков KYB | | `kyb.webhooks:write` | Управление вебхуками KYB | | `kyb.metrics:read` | Чтение метрик KYB | | `kyb.audit:read` | Чтение журнала аудита KYB | | `kyb.reviews:read` | Чтение очереди KYB manual review | | `kyb.reviews:write` | Assign, решения, комментарии, приоритет и resubmit для KYB review tasks | Ручное ревью для интеграторов: [Задачи ревью](/ru/api/review). Каждый эндпоинт требует соответствующий scope; при недостаточных правах доступа возвращается HTTP 403. Поддерживаются wildcard-scopes: `*` (полный доступ) или `applicants:*` (все операции с аппликантами). ## JWT (доступ к сессии верификации) [#jwt-доступ-к-сессии-верификации] После активации ссылки верификации выдаётся краткосрочный JWT-токен. Данный токен используется страницей верификации OneKYC: при переходе пользователя по ссылке все запросы к API (получение данных сессии, загрузка документов, прохождение шагов) выполняются с заголовком `Authorization: Bearer `. Срок действия токена задаётся при создании ссылки (например, 600 секунд). --- **Итог:** серверная интеграция использует HMAC-подпись и API-ключ для вызова Tenant API; доступ пользователя к процедуре верификации обеспечивается JWT-токеном, выданным при активации ссылки. Подробное описание эндпоинтов приведено в разделах [Сессии](/ru/api/sessions) и [Справочник API (OpenAPI)](/ru/api/api-reference).