Содержание

Обзор Аутентификация с помощью API-ключа Схема Bearer Token Реализация OAuth 2.0 Управление JWT-токенами Стратегия ротации ключей Многофакторная аутентификация Рекомендации по безопасности Корпоративные шаблоны Решение проблем

Документация 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-ключа

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_
Область действия	Наследует все разрешения аккаунта, который его создал
Срок действия	Не истекает автоматически; необходимо вручную менять
Ротация	Сгенерируйте новый ключ, перенаправьте трафик, затем деактивируйте старый ключ
Лимиты запросов	Общие для всех запросов, использующих тот же ключ

Bearer Token (Токен-носитель)

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

Получение токенов-носителей

Обменяйте ваш API-ключ и секрет на токен-носитель, действительный в течение 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"
  }'

Формат ответа с токеном

Эндпоинт возвращает токен-носитель с метаданными:

Ответ
{
 "access_token": "eyJhbGciOiJIUzI1NiIs...",
 "token_type": "Bearer",
 "expires_in": 86400,
 "refresh_token": "refresh_1234567..."
}

Использование токенов-носителей

Включайте токен в заголовок 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)

Стандартный поток для веб-приложений:

Пользователь начинает вход — Пользователь нажимает "Подключиться через Smart Money API"
Перенаправление на сервер авторизации — Ваше приложение перенаправляет пользователя на эндпоинт авторизации Smart Money
Пользователь предоставляет разрешение — Пользователь проверяет запрошенные разрешения и предоставляет доступ
Возврат кода авторизации — Пользователь перенаправляется обратно с кодом авторизации
Обмен кода на токен — Бэкенд обменивает код на токен доступа (код никогда не передается во фронтенд)
Хранение токена — Храните refresh token в безопасности; используйте access token для вызовов 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 - обнаружена CSRF-атака');
}
// Обмен кода на токен
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	Доступ к refresh token для получения новых access token без подключения

Управление JWT-токенами

JWT (JSON Web Tokens) обеспечивают аутентификацию без состояния — серверу не нужно хранить данные сессии. Smart Money API использует RS256 (RSA Signature с 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 дней)
Ключи сервисных аккаунтов	Раз в полгода	Ежегодно

Процесс ротации без простоя

Ротируйте ключи без прерывания сервиса:

Создание нового ключа — Создайте новый API-ключ через дашборд или API
Развёртывание нового ключа — Обновите секреты приложения в тестовой среде, тщательно протестируйте
Постепенное внедрение — Разверните на 10% серверов, отслеживайте ошибки
Полное внедрение — Развернуть на оставшихся серверах
Проверить трафик — Убедиться, что все запросы используют новый ключ
Деактивировать старый ключ — Пометить старый ключ как неактивный, но не удалять сразу
Удалить старый ключ — Через 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 одноразовые коды — Менее безопасно, но универсально поддерживается
Подтверждение по электронной почте — Коды подтверждения, отправленные на зарегистрированный email

Включение 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": "Production servers"
  }'

Ведение журналов аудита и соответствие требованиям

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

Событие	Записываемые данные
Аутентификация	Пользователь, временная метка, успех/неудача, IP, статус MFA
Операции с ключами	ID ключа, действие, инициатор, временная метка
Изменения в аккаунте	Что изменилось, кто изменил, временная метка, значения до/после
Доступ к данным	Пользователь, конечная точка, области, временная метка, количество записей

Устранение проблем с аутентификацией

Ошибка недействительного API-ключа

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

Решения:

Проверьте формат ключа (должен начинаться с sk_test_ или sk_live_)
Проверьте наличие пробелов в начале или конце ключа
Убедитесь, что ключ не был деактивирован или заменен
Проверьте, что вы используете правильную среду (тестовый ключ для теста, рабочий для продакшена)
Проверьте, что разрешения API-ключа соответствуют требованиям конечной точки

Ошибка истечения срока действия токена

Проблема: Срок действия токена истек, запросы не выполняются

Решения:

Используйте токен обновления для получения нового токена доступа
Реализуйте автоматическое обновление токена за 5 минут до истечения срока
Храните токен обновления безопасно (не в localStorage для SPA)
Обрабатывайте ответы 401, пытаясь выполнить поток обновления токена

Ошибки CORS/Preflight

Проблема: Браузер блокирует запросы с ошибкой CORS

Решения:

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

MFA Challenge не завершается

Проблема: Операции, требующие MFA, завершаются неудачей даже с правильным кодом

Решения:

Убедитесь, что серверные часы синхронизированы (TOTP зависит от времени)
Код действителен только 30 секунд, сгенерируйте новый
Используйте резервные коды, если приложение аутентификатора недоступно
Восстановление аккаунта доступно через зарегистрированную почту

Реализуйте безопасную аутентификацию сегодня

Smart Money API поддерживает корпоративную аутентификацию с OAuth 2.0, JWT, MFA и интеграцией SAML. Защитите интеграцию API с лучшими отраслевыми практиками.

Посмотреть корпоративные тарифы

Нужен SAML, белый список IP или выделенная поддержка? Свяжитесь с нашей командой продаж.

Продвинутые методы аутентификации — OAuth 2.0, JWT, ротация ключей

Обзор аутентификации

Аутентификация с использованием API-ключа

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

API-ключ в параметре запроса

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

Рекомендации по безопасности API-ключа

Bearer Token (Токен-носитель)

Получение токенов-носителей

Формат ответа с токеном

Использование токенов-носителей

Процедура обновления токена

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

Поток авторизации OAuth 2.0 (Authorization Code Flow)

Шаг 1: Перенаправление пользователя на эндпоинт авторизации

Шаг 2: Обработка колбэка и обмен кода

Области действия OAuth

Управление JWT-токенами

Структура JWT

Заголовок JWT

Утверждения в JWT Payload

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

Стратегия ротации ключей

Частота ротации

Процесс ротации без простоя

Экстренная ротация ключей

Автоматическая ротация в Kubernetes

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

Поддерживаемые методы MFA

Включение TOTP для доступа к учетной записи

MFA во время операций API

Лучшие практики безопасности

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

Безопасность передачи данных

Обработка учетных данных

Логирование и мониторинг

Шаблоны аутентификации для предприятий

Интеграция SAML 2.0

Белый список IP-адресов

Ведение журналов аудита и соответствие требованиям

Устранение проблем с аутентификацией

Ошибка недействительного API-ключа

Ошибка истечения срока действия токена

Ошибки CORS/Preflight

MFA Challenge не завершается

Реализуйте безопасную аутентификацию сегодня

Связанные ресурсы

Руководство по аутентификации →

Лучшие практики безопасности →

Справочник кодов ошибок →