Dokumentacja API
Zaawansowane wzorce uwierzytelniania — OAuth 2.0, JWT, rotacja kluczy
Opanuj zaawansowane mechanizmy uwierzytelniania do integracji Smart Money API w środowiskach przedsiębiorstw. Poznaj przepływy OAuth 2.0, wzorce tokenów JWT, bezpieczną rotację kluczy oraz implementację uwierzytelniania wieloskładnikowego.
Opublikowano 21 marca 2026
•
18 minut czytania
•
Zaawansowane
Przegląd uwierzytelniania
Smart Money API obsługuje wiele metod uwierzytelniania zaprojektowanych tak, aby dostosować się do różnych architektur aplikacji, wymagań bezpieczeństwa i polityk organizacyjnych. Zrozumienie tych wzorców zapewnia, że Twoja integracja jest zarówno bezpieczna, jak i wydajna.
Uwierzytelnianie w Smart Money API działa na trzech podstawowych warstwach:
- Klucze API — Proste uwierzytelnianie tokenem Bearer do rozwoju i prostych integracji
- Tokeny JWT — Tokeny bezstanowe, podpisane kryptograficznie dla systemów rozproszonych i mikrousług
- OAuth 2.0 — Ramy delegowanego autoryzowania dla integracji zewnętrznych i aplikacji SaaS
Zasada bezpieczeństwa: Nigdy nie ujawniaj danych uwierzytelniających w kodzie po stronie klienta, logach, kontroli wersji lub komunikatach o błędach. Wdrażaj rotację danych uwierzytelniających zgodnie z harmonogramem i natychmiast po naruszeniu.
Każda metoda ma odrębne zalety. Klucze API najlepiej sprawdzają się w komunikacji backend-backend, gdzie przechowywanie danych uwierzytelniających jest kontrolowane. Tokeny JWT sprawdzają się w architekturach rozproszonych, gdzie nie ma dostępnego wspólnego stanu. OAuth 2.0 zapewnia dostęp delegowany przez użytkownika dla aplikacji zewnętrznych.
Uwierzytelnianie za pomocą klucza API
Klucze API to najprostszy mechanizm uwierzytelniania — są to losowe ciągi znaków generowane dla Twojego konta, które identyfikują Twoją aplikację w Smart Money API. Każde żądanie musi zawierać Twój klucz API, przekazywany jako nagłówek lub parametr zapytania.
Klucz API oparty na nagłówku
Zalecane podejście to przekazywanie klucza API w nagłówku Authorization przy użyciu schematu Bearer:
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"
Klucz API jako parametr zapytania
W przypadku połączeń WebSocket lub gdy nie można modyfikować nagłówków, przekaż klucz API jako parametr zapytania:
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// Nawiązuje uwierzytelniony strumień WebSocket
Charakterystyka klucza API
| Właściwość |
Opis |
| Format |
128-znakowy ciąg szesnastkowy z prefiksem sk_test_ lub sk_live_ |
| Zakres |
Dziedziczy wszystkie uprawnienia konta, które go utworzyło |
| Wygaśnięcie |
Nigdy nie wygasa automatycznie; musi być ręcznie rotowany |
| Rotacja |
Wygeneruj nowy klucz, migruj ruch, a następnie dezaktywuj stary klucz |
| Limity szybkości |
Współdzielone przez wszystkie żądania korzystające z tego samego klucza |
Praktyki bezpieczeństwa klucza API
- Zmienne środowiskowe — Przechowuj klucze w plikach .env (nie dodawanych do kontroli wersji) i ładuj je w czasie wykonywania
- Systemy skarbców — Używaj HashiCorp Vault, AWS Secrets Manager lub Azure Key Vault w produkcji
- Oddzielne klucze — Zachowuj oddzielne klucze testowe i produkcyjne; często rotuj klucze testowe
- Minimalny zakres — Twórz oddzielne klucze dla różnych integracji, gdy to możliwe
- Rejestrowanie audytu — Rejestruj wszystkie zdarzenia tworzenia i użycia kluczy API
Uzyskaj swój klucz API w 30 sekund
Gotowy do budowania? Pobierz darmowy klucz API (200 wywołań/dzień, bez karty) i zacznij pobierać dane na żywo dotyczące wielorybów, finansowania i danych on-chain.
Uzyskaj swój klucz API →Wzorzec tokenu Bearer
Tokeny Bearer rozszerzają prosty koncept klucza API, dodając kontekst, wygaśnięcie i mechanizmy odświeżania. Są idealne dla aplikacji, które potrzebują programowego zarządzania danymi uwierzytelniającymi.
Uzyskiwanie tokenów Bearer
Wymień swój klucz API i sekret na token Bearer ważny przez 24 godziny:
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"
}'
Format odpowiedzi tokenu
Endpoint zwraca token Bearer z metadanymi:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}
Używanie tokenów Bearer
Dołącz token w nagłówku Authorization dla wszystkich kolejnych żądań:
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Przepływ odświeżania tokenu
Gdy token zbliża się do wygaśnięcia, użyj tokenu odświeżającego, aby uzyskać nowy, bez konieczności podawania sekretu API:
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'
Implementacja OAuth 2.0
OAuth 2.0 umożliwia użytkownikom udzielanie aplikacjom dostępu do ich kont Smart Money API bez udostępniania danych uwierzytelniających. Jest to niezbędne dla platform SaaS, integracji zewnętrznych i aplikacji wielodostępnych.
Przepływ kodu autoryzacyjnego OAuth 2.0
Standardowy przepływ dla aplikacji internetowych:
- Użytkownik inicjuje logowanie — Użytkownik kliknie "Połącz z Smart Money API"
- Przekierowanie do serwera autoryzacyjnego — Twoja aplikacja przekierowuje użytkownika do punktu końcowego autoryzacji Smart Money
- Użytkownik udziela zgody — Użytkownik przegląda żądane zakresy i udziela dostępu
- Zwrot kodu autoryzacyjnego — Użytkownik zostaje przekierowany z powrotem z kodem autoryzacyjnym
- Wymiana kodu na token — Backend wymienia kod na token dostępu (kod nigdy nie jest udostępniany frontendowi)
- Przechowywanie tokenu — Przechowuj token odświeżania bezpiecznie; używaj tokenu dostępu do wywołań API
Krok 1: Przekieruj użytkownika do punktu końcowego autoryzacji
// URL do przekierowania użytkownika
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();
Krok 2: Obsłuż callback i wymień kod
// Backend obsługuje trasę /callback
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// Zweryfikuj parametr state
if (storedState !== receivedState) {
throw new Error('Niezgodność state - wykryto atak CSRF');
}
// Wymień kod na token
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();
// Przechowuj tokeny bezpiecznie
Zakresy OAuth
Żądaj tylko zakresów potrzebnych Twojej aplikacji. Smart Money API definiuje następujące zakresy:
| Zakres |
Opis |
| whales |
Dostęp do śledzenia portfeli wielorybów i metryk akumulacji |
| derivatives |
Dostęp do danych futures, perpetuals i stóp fundingowych |
| onchain |
Dostęp do przepływów transakcji on-chain i analityki |
| alerts |
Twórz i zarządzaj alertami webhook |
| offline |
Dostęp do tokenów odświeżania, aby uzyskać nowe tokeny dostępu offline |
Zarządzanie tokenami JWT
JWT (JSON Web Tokens) zapewniają uwierzytelnianie bezstanowe — serwer nie musi przechowywać danych sesji. Smart Money API używa RS256 (podpis RSA z SHA-256) do podpisywania tokenów, umożliwiając weryfikację bez kontaktu z API.
Struktura JWT
Tokeny JWT składają się z trzech części oddzielonych kropkami:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// NAGŁÓWEK.DANE.PODPIS
Nagłówek JWT
Nagłówek identyfikuje algorytm i typ tokenu:
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}
Oświadczenia (claims) w danych JWT
Dane zawierają oświadczenia (stwierdzenia o użytkowniku/aplikacji):
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}
Weryfikacja podpisów JWT
Pobierz klucz publiczny Smart Money i weryfikuj tokeny przed ich akceptacją:
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Pobierz klucz publiczny z Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// Zweryfikuj token
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// Token jest ważny, użyj zdekodowanych oświadczeń
} catch (err) {
// Token nieprawidłowy lub wygasły
}
Strategia rotacji kluczy
Regularna rotacja kluczy jest kluczowa dla utrzymania bezpieczeństwa. Nawet przy doskonałych praktykach bezpieczeństwa zakładaj, że klucze mogą zostać naruszone i wdrażaj systematyczną rotację.
Częstotliwość rotacji
Smart Money zaleca różne harmonogramy rotacji w zależności od typu klucza i użycia:
| Typ klucza |
Zalecana rotacja |
Minimalna rotacja |
| Testowe klucze API |
Miesięcznie |
Kwartalnie |
| Produkcyjne klucze API |
Kwartalnie |
Rocznie |
| Tokeny odświeżania OAuth |
Automatyczna (po 90 dniach) |
Ręczna (po 180 dniach) |
| Klucze kont usługowych |
Półrocznie |
Rocznie |
Proces rotacji bez przestojów
Rotuj klucze bez przerywania usługi:
- Wygeneruj nowy klucz — Utwórz nowy klucz API przez panel lub API
- Wdróż nowy klucz — Zaktualizuj sekrety aplikacji w środowisku stagingowym, przetestuj dokładnie
- Stopniowe wdrażanie — Wdróż na 10% serwerów, monitoruj pod kątem błędów
- Pełne wdrożenie — Wdróż na pozostałe serwery
- Sprawdź ruch — Potwierdź, że wszystkie żądania używają nowego klucza
- Dezaktywuj stary klucz — Oznacz stary klucz jako nieaktywny, ale nie usuwaj go natychmiast
- Usuń stary klucz — Po 48 godzinach bez błędów trwale usuń
Awaryjna rotacja kluczy
Jeśli podejrzewasz, że klucz został naruszony:
// Natychmiastowe działanie: Dezaktywuj naruszony klucz
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// Wygeneruj zastępczy klucz natychmiast
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "Awaryjny klucz zastępczy"
}'
Automatyczna rotacja w Kubernetes
Użyj Kubernetes Secrets i operatorów do automatycznej rotacji:
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # Co tydzień w niedzielę
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest
Uwierzytelnianie wieloskładnikowe (MFA)
Dla kont z dostępem do danych produkcyjnych, MFA zapewnia dodatkową warstwę bezpieczeństwa, wymagając drugiego czynnika poza samymi poświadczeniami.
Obsługiwane metody MFA
- TOTP (Time-based One-Time Password) — Aplikacje takie jak Google Authenticator, Authy
- WebAuthn/FIDO2 — Klucze sprzętowe, biometria
- Jednorazowe kody SMS — Mniej bezpieczne, ale powszechnie obsługiwane
- Potwierdzenie e-mailem — Kody potwierdzające wysyłane na zarejestrowany e-mail
Włączanie TOTP dla dostępu do konta
// Krok 1: Zażądaj konfiguracji MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// Odpowiedź zawiera URL kodu QR
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}
MFA podczas operacji API
Niektóre operacje mogą wymagać potwierdzenia MFA nawet po uwierzytelnieniu:
// Próba wykonania wrażliwej operacji (rotacja klucza)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// Odpowiedź: Wymagane MFA
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// Ponów próbę z kodem TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"
Najlepsze praktyki bezpieczeństwa
Uwierzytelnianie jest tak silne, jak jego implementacja. Postępuj zgodnie z tymi praktykami, aby zachować bezpieczeństwo:
Zarządzanie sekretami
- Nigdy nie dodawaj sekretów do kontroli wersji — Używaj plików .env z .gitignore
- Używaj zmiennych środowiskowych — Ładuj z bezpiecznych systemów zarządzania sekretami
- Skanuj repozytoria — Używaj narzędzi takich jak TruffleHog, detect-secrets do znajdowania ujawnionych kluczy
- Audytuj dzienniki dostępu — Monitoruj, kto i kiedy uzyskał dostęp do sekretów
Bezpieczeństwo transportu
- Zawsze używaj HTTPS — Nigdy nie wysyłaj poświadczeń przez niezaszyfrowane połączenia
- Weryfikuj certyfikaty SSL — Nie wyłączaj walidacji certyfikatów w produkcji
- Używaj przypinania certyfikatów — Dla aplikacji mobilnych, zapobiegaj atakom MITM
- Wymuszaj TLS 1.2+ — Wyłącz starsze protokoły
Obsługa poświadczeń
- Haszuj sekrety — Przechowuj hashe bcrypt lub Argon2, nigdy w postaci plaintext
- Minimalizuj czas życia — Przechowuj poświadczenia w pamięci tylko tak długo, jak to konieczne
- Wyczyść wrażliwe dane — Jawnie nadpisz poświadczenia po użyciu
- Używaj bezpiecznych bibliotek — Nie implementuj kryptografii samodzielnie
Rejestrowanie i monitorowanie
- Nigdy nie rejestruj poświadczeń — Redaguj klucze w dziennikach, używaj maskowania dzienników
- Rejestruj zdarzenia uwierzytelniania — Śledź udane i nieudane próby logowania
- Monitoruj anomalie — Alarmuj o nietypowych wzorcach dostępu
- Audytuj użycie kluczy — Śledź, które klucze uzyskały dostęp do jakich danych
Wzorce uwierzytelniania dla przedsiębiorstw
Duże organizacje często wymagają dodatkowych kontroli bezpieczeństwa i możliwości zgodności.
Integracja SAML 2.0
Dla klientów korporacyjnych, Smart Money API obsługuje integrację SAML 2.0 z dostawcą tożsamości Twojej organizacji (Okta, Azure AD itp.):
- Single Sign-On (SSO) — Użytkownicy uwierzytelniają się przez korporacyjny IdP
- Automatyczna aprowizacja — Twórz/dezaktywuj konta na podstawie członkostwa w grupach
- Wymuszanie — Wymagaj SAML dla wszystkich dostępu użytkowników
Biała lista IP
Ogranicz dostęp do API do określonych adresów IP lub zakresów CIDR:
// Dodaj IP do białej listy
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "Serwery produkcyjne"
}'
Rejestrowanie zdarzeń i zgodność
Plany enterprise obejmują kompleksowe dzienniki audytowe dla zgodności:
| Zdarzenie |
Zarejestrowane dane |
| Uwierzytelnianie |
Użytkownik, znacznik czasu, sukces/porażka, IP, status MFA |
| Operacje kluczowe |
ID klucza, akcja, inicjator, znacznik czasu |
| Zmiany na koncie |
Co się zmieniło, kto to zmienił, znacznik czasu, wartości przed/po |
| Dostęp do danych |
Użytkownik, endpoint, zakresy, znacznik czasu, liczba rekordów |
Rozwiązywanie problemów z uwierzytelnianiem
Błąd nieprawidłowego klucza API
Problem: Otrzymujesz "401 Unauthorized - Invalid API Key"
Rozwiązania:
- Sprawdź format klucza (powinien zaczynać się od sk_test_ lub sk_live_)
- Sprawdź, czy w kluczu nie ma białych znaków na początku lub końcu
- Potwierdź, że klucz nie został dezaktywowany lub wymieniony
- Upewnij się, że używasz poprawnego środowiska (klucz testowy do testów, produkcyjny do produkcji)
- Sprawdź, czy uprawnienia klucza API pasują do wymagań endpointu
Błąd wygaśnięcia tokena
Problem: Token Bearer wygasł, żądania kończą się niepowodzeniem
Rozwiązania:
- Użyj tokena odświeżającego, aby uzyskać nowy token dostępu
- Zaimplementuj automatyczne odświeżanie tokena 5 minut przed wygaśnięciem
- Przechowuj token odświeżający bezpiecznie (nie w localStorage dla SPA)
- Obsługuj odpowiedzi 401, próbując przepływu tokena odświeżającego
Błędy CORS/Preflight
Problem: Przeglądarka blokuje żądania z błędem CORS
Rozwiązania:
- Wywołania API z przeglądarek muszą pochodzić z białej listy źródeł
- Dodaj swoją domenę przez panel: Ustawienia → Źródła CORS
- Przeglądarka automatycznie wysyła żądanie OPTIONS preflight
- Do celów rozwojowych użyj localhost:3000 lub podobnego
Nieukończone wyzwanie MFA
Problem: Operacje wymagające MFA kończą się niepowodzeniem nawet z poprawnym kodem
Rozwiązania:
- Upewnij się, że zegar serwera jest zsynchronizowany (TOTP zależy od czasu)
- Kod jest ważny tylko przez 30 sekund, wygeneruj nowy
- Użyj kodów zapasowych, jeśli aplikacja autentykacyjna jest niedostępna
- Odzyskiwanie konta dostępne przez zarejestrowany email
Wdroż bezpieczne uwierzytelnianie już dziś
Smart Money API obsługuje uwierzytelnianie klasy enterprise z OAuth 2.0, JWT, MFA i integracją SAML. Zabezpiecz swoją integrację API zgodnie z najlepszymi praktykami branżowymi.
Zobacz plany Enterprise
Potrzebujesz SAML, białej listy IP lub dedykowanego wsparcia? Skontaktuj się z naszym działem sprzedaży.