API-ключи

API-ключ нужен, чтобы пользоваться Fingprint: без него SDK и API не примут запрос. Ключ связывает запросы вашего проекта с группой в кабинете. При создании вы получаете пару ключей:

• Публичный ключ передаётся при настройке браузерного SDK и регистрации Telegram-визитов. По нему Fingprint API определяет проект.
• Приватный ключ хранится только на вашем сервере. Им Fingprint подписывает webhooks, а ваш сервер проверяет подпись. Этим же ключом ваш сервер подписывает запросы на получение данных визитов и профилей через API Fingprint.

Ключи принадлежат группе, которая выбрана в боковом меню. Для каждого проекта или окружения удобно создать отдельный ключ: так события и webhooks будет проще разделять.

Создание ключаСкопировать ссылку

Чтобы создать новую пару API-ключей откройте API-ключи и нажмите Новый ключ. Укажите Название — оно обязательно — и при необходимости Описание. Нажмите Создать API-ключ.

После успешного создания откроется окно "API-ключ создан" с публичным и приватным ключами, скопируйте и сохраните оба значения. Публичный ключ вы всегда сможете посмотреть на странице API-ключи.

Новый ключ появится в таблице со статусом Активен. Передайте публичный ключ в параметр apiKey SDK — см. быстрый старт.

Использование ключаСкопировать ссылку

В таблице API-ключи для каждого ключа видны:

Отправка запроса с приватным ключомСкопировать ссылку

Приватным ключом подписывайте запросы на получение данных визитов и профилей — например, сохранённого профиля посетителя. Для регистрации Telegram-визита достаточно публичного ключа.

Передайте публичный ключ в заголовке X-Public-Key, а в заголовке X-Signature — подпись: HMAC-SHA256 от исходного тела запроса, посчитанный с приватным ключом в качестве секрета, в шестнадцатеричном виде. Сам приватный ключ в запросе не передаётся.

Для браузерного профиля используйте POST /api/v1/fingerprint/visitor/profile, для Telegram-профиля — POST /api/v1/fingerprint/visitor/profile/telegram. В обоих случаях передайте в JSON поле visitor_fp_hash и подпишите отправляемое тело. Параметр sdk не требуется.

Пример запроса POST /api/v1/fingerprint/visitor/profile на Node.js. В visitor_fp_hash передайте значение user, которое вернул agent.get() в браузере:

import crypto from 'node:crypto'

const publicKey = 'pk_live_example'
const privateKey = process.env.FINGPRINT_PRIVATE_KEY!

const body = JSON.stringify({ visitor_fp_hash: 'a1b2c3d4e5f6' })
const signature = crypto.createHmac('sha256', privateKey).update(body).digest('hex')

const response = await fetch('https://gusyrooms.com/api/v1/fingerprint/visitor/profile', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Public-Key': publicKey,
    'X-Signature': signature,
  },
  body,
})

const profile = await response.json()

Fingprint ответит сохранённым профилем посетителя: risk.level — уровень риска (no, low, medium или high), статистика визитов в statistics и данные последнего визита и VPN в latest_visit и latest_vpn.

Отключение ключаСкопировать ссылку

Отключите ключ, если нужно временно остановить приём запросов, но сохранить его настройки. Откройте меню в строке ключа, выберите Редактировать, в поле Статус ключа выберите Отключён и нажмите Сохранить.

Запросы с отключённым ключом Fingprint API отклоняет со статусом 403. SDK вернёт ошибку API_HTTP_ERROR, а error.status будет равен 403. Чтобы снова принимать запросы, выберите статус Активен.

Удаление ключаСкопировать ссылку

Откройте меню в строке ключа, выберите Удалить и подтвердите действие. Удаление необратимо.