Додатки та ключі (Apps & Keys)
Кожна інтеграція з Quasar починається зі створення додатка (App): саме він володіє синхронізованими транзакціями, точками підключення вебхуків та API-ключами. У Quasar Cloud додаток належить організації (до 30 додатків на кожну); версія Community Edition використовує єдиний робочий простір.
🛠️ Створення додатка
У панелі керування Quasar (або в панелі /admin вашої власної ноди) відкрийте розділ Apps та натисніть «Створити додаток». Оберіть середовище (environment):
- Live — для реального продакшн-трафіку. Ключі мають префікси
sk_live_таpk_live_. - Test — для розробки та тестування. Ключі починаються з
sk_test_таpk_test_, а вартість синхронізації транзакцій удвічі менша, ніж у Live (дивіться Квоти та ліміти).
Обидва середовища відстежують транзакції за абсолютно однаковими алгоритмами та правилами консенсусу.
🔑 Секретний та публічний ключі
| Тип ключа | Префікс | Заголовок HTTP | Дозволені операції |
|---|---|---|---|
| Secret key | sk_live_, sk_test_ | x-tuwa-secret-key | Усі ендпоінти: синхронізація транзакцій, керування вебхуками, читання історії |
| Public key | pk_live_, pk_test_ | x-tuwa-public-key | Тільки безпечні read-only запити без доступу до персональних даних (наприклад, GET /v1/engine/test-ping) |
- Зберігайте секретний ключ виключно на бекенді (змінна оточення, Next.js Server Action, API Route). Будь-хто, хто заволодіє секретним ключем, зможе синхронізувати транзакції від імені вашого додатку та витрачати його квоту. Пакет
@tuwaio/quasar-sdkпередає заголовок автоматично:
import { Quasar } from '@tuwaio/quasar-sdk'; export const quasar = new Quasar({ secretKey: process.env.QUASAR_SECRET_KEY ?? '' });- Публічний ключ призначений лише для читання і не надає доступу до даних ваших користувачів: будь-який
POST-запит або запит історії з публічним ключем відхиляється зі статусом403 Forbidden. Читайте історію транзакцій на власному сервері за допомогою секретного ключа і показуйте користувачеві лише операції його власного верифікованого гаманця (перевіряйте сесію SIWX перед запитом). - Безпечне збереження: Quasar зберігає секретні ключі у зашифрованому вигляді та шукає їх за криптографічним хешем SHA-256. Перегляд ключа в панелі керування вимагає введення пароля (та коду 2FA, якщо його ввімкнено).
- Ротація ключів: оновлення (рол) секретного ключа в налаштуваннях додатку миттєво генерує новий ключ і блокує старий. Одразу після цього оновіть змінні оточення на вашому продакшн-сервері.
🛡️ Налаштування безпеки та фільтрації
| Параметр | Ефект і поведінка |
|---|---|
| Active | Вимкнений додаток миттєво відхиляє будь-які вхідні запити до API зі статусом 403 Forbidden. |
| IP allowlist | Якщо список не порожній, дозволяються лише запити з указаних IP-адрес (решта отримують 403). |
| Domain allowlist | Якщо список не порожній, запити повинні містити заголовки Origin або Referer із дозволеного списку доменів. Запити типу Server-to-Server з @tuwaio/quasar-sdk таких заголовків не надсилають, тому для серверних додатків залишайте це поле порожнім. |
У налаштуваннях додатку також вказуються ваші власні провайдери RPC та ключі (Alchemy, QuickNode, Pimlico) для механізмів трекінгу. Quasar зберігає їх у зашифрованому вигляді та блокує будь-які приватні та loopback адреси вузлів.
422 Unprocessable Entity без збереження в базі. Спільнотна версія (Community Edition) додатково підтримує глобальні резервні RPC оператора та відстеження операцій Safe.🏢 Сувора ізоляція між додатками
Quasar ідентифікує додаток за ключем у кожному запиті та взаємодіє виключно з транзакціями цього конкретного додатка: історія одного додатку ніколи не містить транзакцій іншого, навіть якщо вони належать до однієї організації. Доставка вебхуків додатково валідується за ідентифікаторами організації та додатку перед кожною відправкою.