Документація API

Розширені шаблони автентифікації — OAuth 2.0, JWT, ротація ключів

Опануйте складні механізми автентифікації для інтеграції Smart Money API у корпоративних середовищах. Дізнайтеся про потоки OAuth 2.0, шаблони JWT-токенів, безпечну ротацію ключів та реалізацію багатофакторної автентифікації.

Опубліковано 21 березня 2026 року • 18 хв читання • Просунутий

Огляд автентифікації

Smart Money API підтримує кілька методів автентифікації, розроблених для задоволення різних архітектур додатків, вимог безпеки та організаційних політик. Розуміння цих шаблонів забезпечує безпеку та продуктивність вашої інтеграції.

Автентифікація в Smart Money API працює на трьох основних рівнях:

  • API-ключами — Проста автентифікація за допомогою bearer token для розробки та простих інтеграцій
  • JWT-токени — Безстані, криптографічно підписані токени для розподілених систем та мікросервісів
  • OAuth 2.0 — Делегована структура авторизації для інтеграцій сторонніх розробників та SaaS-додатків

Принцип безпеки: Ніколи не розкривайте дані автентифікації у клієнтському коді, логах, системах контролю версій або повідомленнях про помилки. Впроваджуйте ротацію облікових даних за розкладом та негайно після компрометації.

Кожен метод має свої переваги. API-ключами найкраще користуватися для зв’язку між серверними системами, де зберігання облікових даних контролюється. JWT-токени чудово підходять для розподілених архітектур, де немає спільного стану. OAuth 2.0 надає доступ, делегований користувачем, для сторонніх додатків.

API Key Authentication

API-ключі — це найпростіший механізм аутентифікації. Це випадкові рядки, згенеровані для вашого облікового запису, які ідентифікують ваш додаток у Smart Money API. Кожен запит повинен містити ваш API-ключ у заголовку або параметрі запиту.

API-ключ у заголовку

Рекомендований спосіб — передача API-ключа в заголовку Authorization за схемою Bearer:

curl Приклад
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"

API-ключ у параметрі запиту

Для WebSocket-зʼєднань або коли заголовки не можна змінити, передайте API-ключ як параметр запиту:

WebSocket-зʼєднання
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// Встановлює аутентифікований WebSocket-потік

Характеристики API-ключа

Властивість Опис
Формат 128-символьний рядок у шістнадцятковому форматі з префіксом sk_test_ або sk_live_
Область дії Успадковує всі дозволи облікового запису, який його створив
Термін дії Не закінчується автоматично; потрібно змінювати вручну
Заміна Згенеруйте новий ключ, перенесіть трафік, а потім деактивуйте старий ключ
Обмеження запитів Діють для всіх запитів, що використовують той самий ключ

Практики безпеки API-ключа

  • Змінні середовища — Зберігайте ключі у файлах .env (не додавайте їх до системи контролю версій) і завантажуйте під час виконання
  • Системи зберігання ключів — Використовуйте HashiCorp Vault, AWS Secrets Manager або Azure Key Vault у продакшені
  • Окремі ключі — Використовуйте окремі тестові та бойові ключі; регулярно змінюйте тестові ключі
  • Мінімальний обсяг — Створюйте окремі ключі для різних інтеграцій, де це можливо
  • Журналювання аудиту — Фіксуйте всі події створення та використання API-ключів
Отримайте ваш API-ключ за 30 секунд

Готові будувати? Отримайте безкоштовний API-ключ (100 запитів/день, без картки) та почніть отримувати дані про китов, фандінг та ончейн-активність.

Отримайте ваш API-ключ →

Схема Bearer Token

Bearer токени розширюють концепцію простих API-ключів, додаючи контекст, термін дії та механізми оновлення. Вони ідеальні для додатків, які потребують програмного управління обліковими даними.

Отримання Bearer токенів

Обміняйте ваш API-ключ та секрет на bearer токен, дійсний протягом 24 годин:

GET /auth/token
curl -X POST "https://api.smartmoneyapi.com/v1/auth/token" \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk_live_1234567890",
"api_secret": "secret_abc123xyz"
}'

Формат відповіді токена

Кінцева точка повертає bearer токен з метаданими:

Відповідь
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}

Використання Bearer токенів

Додавайте токен до заголовка Authorization для всіх наступних запитів:

Автентифікований запит
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Процес оновлення токена

Коли токен наближається до закінчення терміну дії, використовуйте refresh токен для отримання нового без необхідності вводити API-секрет:

POST /auth/refresh
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'

Реалізація OAuth 2.0

OAuth 2.0 дозволяє користувачам надавати додаткам доступ до їхніх облікових записів Smart Money API без передачі облікових даних. Це важливо для SaaS-платформ, сторонніх інтеграцій та багатокористувацьких додатків.

OAuth 2.0 Authorization Code Flow

Стандартний процес для вебдодатків:

  1. Користувач ініціює вхід — Користувач натискає "Підключитися через Smart Money API"
  2. Перенаправлення на сервер авторизації — Ваш додаток перенаправляє користувача на кінцеву точку авторизації Smart Money
  3. Користувач надає дозвіл — Користувач перевіряє запитувані дозволи та надає доступ
  4. Повернення коду авторизації — Користувача перенаправлено назад з кодом авторизації
  5. Обмін коду на токен — Бекенд обмінює код на токен доступу (код ніколи не передається на фронтенд)
  6. Збереження токена — Зберігайте токен оновлення безпечно; використовуйте токен доступу для викликів API

Крок 1: Перенаправлення користувача на кінцеву точку авторизації

Перенаправлення на фронтенді
// URL для перенаправлення користувача
const authUrl = new URL('https://api.smartmoneyapi.com/oauth/authorize');
authUrl.searchParams.append('client_id', 'your_client_id');
authUrl.searchParams.append('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.append('response_type', 'code');
authUrl.searchParams.append('scope', 'whales derivatives onchain');
authUrl.searchParams.append('state', generateRandomState());
window.location.href = authUrl.toString();

Крок 2: Обробка зворотного виклику та обмін коду

Обмін коду на бекенді
// Бекенд обробляє маршрут /callback
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// Перевірка параметра state
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// Обмін коду на токен
const tokenResponse = await fetch('https://api.smartmoneyapi.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'authorization_code',
code: code,
client_id: process.env.OAUTH_CLIENT_ID,
client_secret: process.env.OAUTH_CLIENT_SECRET,
redirect_uri: 'https://yourapp.com/callback'
})
});
const tokens = await tokenResponse.json();
// Безпечне зберігання токенів

Обсяги OAuth

Запитуйте лише обсяги, які потрібні вашому додатку. Smart Money API визначає такі обсяги:

Обсяг Опис
whales Доступ до відстеження гаманців китів та метрик накопичення
derivatives Доступ до даних ф'ючерсів, перпетуалів та ставок фандінгу
onchain Доступ до ончейн-транзакцій та аналітики
alerts Створення та керування сповіщеннями через вебхуки
offline Доступ до токенів оновлення для отримання нових токенів доступу офлайн

Керування JWT-токенами

JWT (JSON Web Tokens) забезпечують автентифікацію без стану — серверу не потрібно зберігати дані сеансу. Smart Money API використовує RS256 (RSA Signature with SHA-256) для підпису токенів, що дозволяє перевірку без звернення до API.

Структура JWT

JWT-токени складаються з трьох частин, розділених крапками:

Формат JWT
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// HEADER.PAYLOAD.SIGNATURE

Заголовок JWT

Заголовок визначає алгоритм та тип токена:

Декодований заголовок
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}

Клейми JWT Payload

Payload містить клейми (твердження про користувача/додаток):

Декодований Payload
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}

Перевірка підписів JWT

Завантажте публічний ключ Smart Money та перевіряйте токени перед їх прийняттям:

Перевірка в Node.js
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Отримати публічний ключ від Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// Перевірити токен
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// Токен дійсний, використовуйте декодовані клейми
} catch (err) {
// Токен недійсний або протермінований
}

Стратегія обертання ключів

Регулярне обертання ключів є критично важливим для підтримки безпеки. Навіть при ідеальних практиках безпеки, припускайте, що ключі можуть бути скомпрометовані, та реалізуйте систематичне обертання.

Частота обертання

Smart Money рекомендує різні графіки обертання залежно від типу ключа та його використання:

Тип ключа Рекомендоване обертання Мінімальне обертання
Тестові API-ключа Щомісяця Щокварталу
Продуктивні API-ключа Щокварталу Щороку
OAuth Refresh Tokens Автоматичне (після 90 днів) Ручне (після 180 днів)
Ключі сервісних акаунтів Піврічно Щороку

Процес обертання без простоїв

Обертайте ключі без перерв у роботі сервісу:

  1. Згенерувати новий ключ — Створіть новий API-ключ через інтерфейс або API
  2. Розгорнути новий ключ — Оновіть секрети додатка в тестовому середовищі, ретельно перевірте
  3. Поступове розгортання — Розгорніть на 10% серверів, моніторьте на помилки
  4. Повний запуск — Розгортання на решті серверів
  5. Перевірка трафіку — Підтвердьте, що всі запити використовують новий ключ
  6. Деактивувати старий ключ — Позначте старий ключ як неактивний, але не видаляйте його негайно
  7. Видалити старий ключ — Через 48 годин без помилок остаточно видаліть

Аварійна ротація ключів

Якщо ви підозрюєте, що ключ скомпрометований:

Аварійна ротація
// Негайні дії: Деактивуйте скомпрометований ключ
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// Згенеруйте заміну ключа негайно
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "Аварійний ключ заміни"
}'

Автоматизована ротація в Kubernetes

Використовуйте Kubernetes Secrets та оператори для автоматичної ротації:

CronJob для ротації ключів
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # Щотижня в неділю
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest

Багатофакторна аутентифікація (MFA)

Для облікових записів, які мають доступ до виробничих даних, MFA забезпечує додатковий рівень безпеки, вимагаючи другого фактора окрім просто облікових даних.

Підтримувані методи MFA

  • TOTP (Одноразовий пароль на основі часу) — Додатки, такі як Google Authenticator, Authy
  • WebAuthn/FIDO2 — Апаратні ключі безпеки, біометрія
  • SMS одноразові коди — Менш безпечні, але універсально підтримуються
  • Підтвердження електронною поштою — Коди підтвердження надсилаються на зареєстровану електронну пошту

Увімкнення TOTP для доступу до облікового запису

Увімкніть MFA
// Крок 1: Запит на налаштування MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// Відповідь містить URL QR-коду
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}

MFA під час операцій API

Деякі операції можуть вимагати підтвердження MFA навіть після аутентифікації:

Запит MFA
// Спроба виконати чутливу операцію (ротація ключів)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// Відповідь: Потрібно MFA
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// Повторіть спробу з кодом TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"

Найкращі практики безпеки

Аутентифікація настільки сильна, наскільки її реалізація. Дотримуйтесь цих практик для підтримки безпеки:

Управління секретами

  • Ніколи не зберігайте секрети у системі контролю версій — Використовуйте файли .env з .gitignore
  • Використовуйте змінні середовища — Завантажуйте з безпечних систем управління секретами
  • Скануйте репозиторії — Використовуйте інструменти, такі як TruffleHog, detect-secrets, для пошуку викритих ключів
  • Аудит журналів доступу — Слідкуйте, хто отримав доступ до секретів і коли

Безпека транспортування

  • Завжди використовуйте HTTPS — Ніколи не надсилайте облікові дані через незашифровані з'єднання
  • Перевіряйте SSL-сертифікати — Не вимикайте перевірку сертифікатів у виробництві
  • Використовуйте прив'язку сертифікатів — Для мобільних додатків, запобігайте атакам MITM
  • Застосовуйте TLS 1.2+ — Вимкніть старіші протоколи

Обробка облікових даних

  • Хешуйте секрети — Зберігайте bcrypt або Argon2 хеші, ніколи у відкритому вигляді
  • Мінімізуйте термін дії — Зберігайте облікові дані в пам'яті лише стільки, скільки потрібно
  • Очищуйте чутливі дані — Явно перезаписуйте облікові дані після використання
  • Використовуйте безпечні бібліотеки — Не реалізуйте криптографію самостійно

Логування та моніторинг

  • Ніколи не логуйте облікові дані — Приховуйте ключі в логах, використовуйте маскування логів
  • Логуйте події аутентифікації — Відстежуйте успішні та невдалі спроби входу
  • Слідкуйте за аномаліями — Повідомляйте про незвичайні шаблони доступу
  • Аудит використання ключів — Відстежуйте, які ключі отримали доступ до яких даних

Шаблони аутентифікації для підприємств

Великі організації часто потребують додаткових заходів безпеки та можливостей відповідності.

Інтеграція SAML 2.0

Для корпоративних клієнтів Smart Money API підтримує інтеграцію SAML 2.0 з вашим постачальником ідентифікації (Okta, Azure AD тощо):

  • Єдиний вхід (SSO) — Користувачі аутентифікуються через ваш корпоративний IdP
  • Автоматичне надання прав — Створюйте/вимикайте облікові записи на основі членства в групах
  • Примусове використання — Вимагайте SAML для всіх доступів користувачів

Білий список IP

Обмежте доступ до API за конкретними IP-адресами або діапазонами CIDR:

Управління IP-білими списками
// Додати IP до білого списку
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "Виробничі сервери"
}'

Ведення журналів аудиту та відповідність

Корпоративні плани включають комплексні журнали аудиту для відповідності:

Подія Записані дані
Аутентифікація Користувач, часова мітка, успіх/невдача, IP, статус MFA
Операції з ключами ID ключа, дія, ініціатор, часова мітка
Зміни в обліковому записі Що змінено, хто змінив, часова мітка, значення до/після
Доступ до даних Користувач, кінцева точка, області, часова мітка, кількість записів

Виправлення проблем із аутентифікацією

Помилка недійсного API-ключа

Проблема: Отримано "401 Unauthorized - Invalid API Key"

Рішення:

  • Перевірте формат ключа (повинен починатися з sk_test_ або sk_live_)
  • Перевірте наявність пробілів на початку або в кінці ключа
  • Підтвердьте, що ключ не був деактивований або замінений
  • Перевірте, що ви використовуєте правильне середовище (тестовий ключ для тестування, живий для виробництва)
  • Перевірте, що дозволи API-ключа відповідають вимогам кінцевої точки

Помилка закінчення терміну дії токена

Проблема: Термін дії токена Bearer закінчився, запити не виконуються

Рішення:

  • Використовуйте токен оновлення для отримання нового токена доступу
  • Реалізуйте автоматичне оновлення токена за 5 хвилин до закінчення терміну дії
  • Зберігайте токен оновлення безпечно (не в localStorage для SPA)
  • Обробляйте відповіді 401, намагаючись виконати потік оновлення токена

Помилки CORS/Preflight

Проблема: Браузер блокує запити з помилкою CORS

Рішення:

  • Виклики API з браузерів повинні надходити з дозволених джерел
  • Додайте свій домен через панель керування: Налаштування → CORS Origins
  • Браузер автоматично надсилає запит OPTIONS preflight
  • Для розробки використовуйте localhost:3000 або подібне

Проблема завершення виклику MFA

Проблема: Операції, що вимагають MFA, не вдаються навіть з правильним кодом

Рішення:

  • Переконайтеся, що серверний годинник синхронізований (TOTP залежить від часу)
  • Код дійсний лише 30 секунд, згенеруйте новий
  • Використовуйте резервні коди, якщо додаток для автентифікації недоступний
  • Відновлення облікового запису доступне через зареєстровану електронну пошту

Впровадьте безпечну аутентифікацію сьогодні

Smart Money API підтримує корпоративну аутентифікацію з OAuth 2.0, JWT, MFA та інтеграцію SAML. Захистіть свою інтеграцію API за допомогою найкращих практик галузі.

Переглянути корпоративні плани
Потрібен SAML, IP-білий список або спеціальна підтримка? Зв’яжіться з нашим відділом продажів.

Пов’язані ресурси

Посібник з аутентифікації →

Початок роботи з аутентифікацією API

Найкращі практики безпеки →

Комплексний посібник із забезпечення безпеки

Довідник кодів помилок →

Виправлення помилок аутентифікації
Почніть безкоштовно — 100 викликів/день, без картки

Отримуйте живий потік китів, фінансування, відкритий інтерес та дані on-chain з 3 бірж через один API. Безкоштовний рівень, без кредитної картки, оновлення будь-коли.

Почніть безкоштовно →
Спробуйте живу консоль API → (обліковий запис не потрібен)