Documentazione API
Patterns Avanzati di Autenticazione — OAuth 2.0, JWT, Rotazione delle Chiavi
Padroneggia meccanismi di autenticazione sofisticati per integrare Smart Money API in ambienti aziendali. Impara i flussi OAuth 2.0, i pattern dei token JWT, la rotazione sicura delle chiavi e l'implementazione dell'autenticazione multi-fattore.
Pubblicato il 21 marzo 2026
•
18 min di lettura
•
Avanzato
Panoramica sull'Autenticazione
Smart Money API supporta molteplici metodi di autenticazione progettati per adattarsi a diverse architetture applicative, requisiti di sicurezza e politiche organizzative. Comprendere questi pattern garantisce che la tua integrazione sia sia sicura che performante.
L'autenticazione in Smart Money API opera su tre livelli principali:
- Chiavi API — Autenticazione semplice con token bearer per sviluppo e integrazioni dirette
- Token JWT — Token crittograficamente firmati senza stato per sistemi distribuiti e microservizi
- OAuth 2.0 — Framework di autorizzazione delegata per integrazioni di terze parti e applicazioni SaaS
Principio di Sicurezza: Non esporre mai le credenziali di autenticazione nel codice client, nei log, nel controllo versione o nei messaggi di errore. Implementa la rotazione delle credenziali secondo una pianificazione e immediatamente in caso di compromissione.
Ogni metodo ha vantaggi distinti. Le chiavi API funzionano meglio per la comunicazione backend-to-backend dove lo storage delle credenziali è controllato. I token JWT eccellono in architetture distribuite dove non è disponibile uno stato condiviso. OAuth 2.0 fornisce accesso delegato per applicazioni di terze parti.
Autenticazione con Chiave API
Le chiavi API sono il meccanismo di autenticazione più semplice—sono stringhe casuali generate per il tuo account che identificano la tua applicazione su Smart Money API. Ogni richiesta deve includere la tua chiave API come header o parametro di query.
Chiave API basata su Header
L'approccio consigliato è passare la tua chiave API nell'header Authorization usando lo schema Bearer:
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"
Chiave API come Parametro di Query
Per connessioni WebSocket o quando gli header non possono essere modificati, passa la chiave API come parametro di query:
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// Stabilisce uno stream WebSocket autenticato
Caratteristiche delle Chiavi API
| Proprietà |
Descrizione |
| Formato |
Stringa esadecimale di 128 caratteri con prefisso sk_test_ o sk_live_ |
| Ambito |
Eredita tutti i permessi dell'account che l'ha creata |
| Scadenza |
Non scade automaticamente; deve essere ruotata manualmente |
| Rotazione |
Genera una nuova chiave, migra il traffico, poi disattiva la vecchia chiave |
| Limiti di Frequenza |
Condivisi tra tutte le richieste che usano la stessa chiave |
Pratiche di Sicurezza per le Chiavi API
- Variabili d'Ambiente — Archivia le chiavi in file .env (non commitati nel controllo versione) e caricale a runtime
- Sistemi di Vault — Usa HashiCorp Vault, AWS Secrets Manager o Azure Key Vault in produzione
- Chiavi Separate — Mantieni chiavi di test e produzione separate; ruota frequentemente le chiavi di test
- Ambito Minimale — Crea chiavi separate per diverse integrazioni quando possibile
- Registrazione di Audit — Registra tutti gli eventi di creazione e utilizzo delle chiavi API
Ottieni la tua chiave API in 30 secondi
Pronto a sviluppare? Ottieni una chiave API gratuita (200 chiamate/giorno, senza carta) e inizia a recuperare dati live su whale, funding e on-chain.
Ottieni la tua chiave API →Pattern del Token Bearer
I token bearer estendono il concetto semplice della chiave API aggiungendo contesto, scadenza e meccanismi di refresh. Sono ideali per applicazioni che necessitano di gestione programmatica delle credenziali.
Ottenere Token Bearer
Scambia la tua chiave API e il segreto per un token bearer valido per 24 ore:
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"
}'
Formato della Risposta del Token
L'endpoint restituisce un token bearer con metadati:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}
Utilizzo dei Token Bearer
Includi il token nell'header Authorization per tutte le richieste successive:
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Flusso di Refresh del Token
Quando un token si avvicina alla scadenza, usa il refresh token per ottenerne uno nuovo senza richiedere il tuo API secret:
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'
Implementazione OAuth 2.0
OAuth 2.0 consente agli utenti di concedere alle applicazioni l'accesso ai loro account Smart Money API senza condividere le credenziali. Questo è essenziale per piattaforme SaaS, integrazioni di terze parti e applicazioni multi-tenant.
Flusso di Codice di Autorizzazione OAuth 2.0
Il flusso standard per applicazioni web:
- Utente Inizia il Login — L'utente clicca "Connetti con Smart Money API"
- Reindirizzamento al Server di Autorizzazione — La tua app reindirizza l'utente all'endpoint di autorizzazione di Smart Money
- Utente Concede il Permesso — L'utente rivede gli ambiti richiesti e concede l'accesso
- Codice di Autorizzazione Restituito — L'utente viene reindirizzato indietro con il codice di autorizzazione
- Scambio del Codice con il Token — Il backend scambia il codice con un token di accesso (il codice non è mai esposto al frontend)
- Archivia il Token — Memorizza il token di aggiornamento in modo sicuro; utilizza il token di accesso per le chiamate API
Passaggio 1: Reindirizza l'utente all'endpoint di autorizzazione
// URL per reindirizzare l'utente
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();
Passaggio 2: Gestisci il callback e scambia il codice
// Il backend gestisce la rotta /callback
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// Verifica il parametro state
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// Scambia il codice con il 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();
// Memorizza i token in modo sicuro
Scope OAuth
Richiedi solo gli scope necessari alla tua applicazione. Smart Money API definisce questi scope:
| Scope |
Descrizione |
| whales |
Accesso al tracciamento dei portafogli delle balene e alle metriche di accumulo |
| derivatives |
Accesso ai dati su futures, perpetuals e funding rate |
| onchain |
Accesso ai flussi di transazioni on-chain e alle analisi |
| alerts |
Crea e gestisci alert via webhook |
| offline |
Accesso ai token di aggiornamento per ottenere nuovi token di accesso offline |
Gestione dei token JWT
I JWT (JSON Web Tokens) forniscono autenticazione stateless—il server non deve memorizzare dati di sessione. Smart Money API utilizza RS256 (Firma RSA con SHA-256) per la firma dei token, permettendo la verifica senza contattare l'API.
Struttura JWT
I token JWT consistono di tre parti separate da punti:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// HEADER.PAYLOAD.SIGNATURE
Header JWT
L'header identifica l'algoritmo e il tipo di token:
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}
Claim del payload JWT
Il payload contiene i claim (dichiarazioni sull'utente/app):
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}
Verifica delle firme JWT
Scarica la chiave pubblica di Smart Money e verifica i token prima di accettarli:
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Ottieni la chiave pubblica da Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// Verifica il token
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// Il token è valido, utilizza i claim decodificati
} catch (err) {
// Token non valido o scaduto
}
Strategia di rotazione delle chiavi
La rotazione regolare delle chiavi è fondamentale per mantenere la sicurezza. Anche con pratiche di sicurezza perfette, presupponi che le chiavi possano essere compromesse e implementa una rotazione sistematica.
Frequenza di rotazione
Smart Money raccomanda diversi programmi di rotazione in base al tipo di chiave e all'utilizzo:
| Tipo di chiave |
Rotazione consigliata |
Rotazione minima |
| Chiavi API di test |
Mensile |
Trimestrale |
| Chiavi API di produzione |
Trimestrale |
Annuale |
| Token di aggiornamento OAuth |
Automatica (dopo 90 giorni) |
Manuale (dopo 180 giorni) |
| Chiavi degli account di servizio |
Semestrale |
Annuale |
Processo di rotazione senza tempi di inattività
Ruota le chiavi senza interrompere il servizio:
- Genera una nuova chiave — Crea una nuova chiave API tramite dashboard o API
- Distribuisci la nuova chiave — Aggiorna i segreti dell'applicazione in staging, testa accuratamente
- Rollout graduale — Distribuisci al 10% dei server, monitora gli errori
- Implementazione Completa — Distribuisci sui server rimanenti
- Verifica Traffico — Conferma che tutte le richieste utilizzino la nuova chiave
- Disattiva Vecchia Chiave — Contrassegna la vecchia chiave come inattiva ma non eliminarla immediatamente
- Elimina Vecchia Chiave — Dopo 48 ore senza errori, elimina definitivamente
Rotazione di Emergenza delle Chiavi
Se sospetti che una chiave sia compromessa:
// Azione immediata: Disattiva la chiave compromessa
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// Genera una chiave sostitutiva immediatamente
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "Chiave Sostitutiva di Emergenza"
}'
Rotazione Automatica in Kubernetes
Utilizza Kubernetes Secrets e operatori per la rotazione automatica:
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # Settimanalmente la domenica
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest
Autenticazione a Multi-Fattore (MFA)
Per gli account che accedono ai dati di produzione, l'MFA fornisce un ulteriore livello di sicurezza richiedendo un secondo fattore oltre alle credenziali.
Metodi MFA Supportati
- TOTP (Password Monouso a Tempo) — App come Google Authenticator, Authy
- WebAuthn/FIDO2 — Chiavi di sicurezza hardware, biometriche
- Codici Monouso via SMS — Meno sicuri ma universalmente supportati
- Conferma via Email — Codici di conferma inviati all'email registrata
Abilitazione TOTP per l'Accesso all'Account
// Passo 1: Richiedi la configurazione MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// La risposta include l'URL del QR code
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}
MFA Durante le Operazioni API
Alcune operazioni potrebbero richiedere la conferma MFA anche dopo l'autenticazione:
// Tentativo di operazione sensibile (rotazione chiave)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// Risposta: MFA richiesto
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// Riprova con il codice TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"
Migliori Pratiche di Sicurezza
L'autenticazione è forte solo quanto la sua implementazione. Segui queste pratiche per mantenere la sicurezza:
Gestione dei Segreti
- Non inserire mai segreti nel controllo versione — Usa file .env con .gitignore
- Usa variabili d'ambiente — Carica da sistemi sicuri di gestione dei segreti
- Scansiona i repository — Usa strumenti come TruffleHog, detect-secrets per trovare chiavi esposte
- Controlla i log di accesso — Monitora chi ha accesso ai segreti e quando
Sicurezza del Trasporto
- Usa sempre HTTPS — Non inviare mai credenziali su connessioni non cifrate
- Verifica i certificati SSL — Non disabilitare la validazione dei certificati in produzione
- Usa il pinning dei certificati — Per le app mobile, previeni attacchi MITM
- Impone TLS 1.2+ — Disabilita i protocolli più vecchi
Gestione delle Credenziali
- Hash dei segreti — Memorizza hash bcrypt o Argon2, mai in chiaro
- Minimizza la durata — Mantieni le credenziali in memoria solo per il tempo necessario
- Cancella i dati sensibili — Sovrascrivi esplicitamente le credenziali dopo l'uso
- Usa librerie sicure — Non implementare la crittografia da solo
Registrazione e Monitoraggio
- Non registrare mai le credenziali — Oscura le chiavi nei log, usa il mascheramento dei log
- Registra gli eventi di autenticazione — Traccia tentativi di accesso riusciti e falliti
- Monitora le anomalie — Avvisa su modelli di accesso insoliti
- Controlla l'uso delle chiavi — Traccia quali chiavi hanno accesso a quali dati
Modelli di Autenticazione Aziendale
Le grandi organizzazioni spesso richiedono controlli di sicurezza aggiuntivi e capacità di conformità.
Integrazione SAML 2.0
Per i clienti aziendali, Smart Money API supporta l'integrazione SAML 2.0 con il provider di identità della tua organizzazione (Okta, Azure AD, ecc.):
- Single Sign-On (SSO) — Gli utenti si autenticano tramite il tuo IdP aziendale
- Provisioning automatico — Crea/disattiva account in base all'appartenenza al gruppo
- Imposizione — Richiedi SAML per tutti gli accessi utente
Whitelist IP
Limita l'accesso API a indirizzi IP o intervalli CIDR specifici:
// Aggiungi IP alla whitelist
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "Server di produzione"
}'
Registri di Audit e Conformità
I piani Enterprise includono registri di audit completi per la conformità:
| Evento |
Dati Registrati |
| Autenticazione |
Utente, timestamp, successo/fallimento, IP, stato MFA |
| Operazioni con Chiavi |
ID chiave, azione, iniziatore, timestamp |
| Modifiche all'Account |
Cosa è cambiato, chi lo ha modificato, timestamp, valori prima/dopo |
| Accesso ai Dati |
Utente, endpoint, ambiti, timestamp, conteggio record |
Risoluzione dei Problemi di Autenticazione
Errore di Chiave API Non Valida
Problema: Ricezione "401 Unauthorized - Invalid API Key"
Soluzioni:
- Verifica il formato della chiave (dovrebbe iniziare con sk_test_ o sk_live_)
- Controlla spazi bianchi iniziali/finali nella chiave
- Conferma che la chiave non sia stata disattivata o ruotata
- Verifica che stai utilizzando l'ambiente corretto (chiave test per test, live per produzione)
- Controlla che i permessi della chiave API corrispondano ai requisiti dell'endpoint
Errore di Token Scaduto
Problema: Token Bearer scaduto, richieste fallite
Soluzioni:
- Usa il token di refresh per ottenere un nuovo token di accesso
- Implementa il refresh automatico del token 5 minuti prima della scadenza
- Archivia il token di refresh in modo sicuro (non in localStorage per SPA)
- Gestisci le risposte 401 tentando il flusso di refresh del token
Errori CORS/Preflight
Problema: Il browser blocca le richieste con errore CORS
Soluzioni:
- Le chiamate API dai browser devono provenire da origini whitelistate
- Aggiungi il tuo dominio tramite dashboard: Impostazioni → Origini CORS
- Il browser invia automaticamente una richiesta OPTIONS preflight
- Per sviluppo, usa localhost:3000 o simili
MFA Challenge Non Completato
Problema: Operazioni che richiedono MFA falliscono anche con il codice corretto
Soluzioni:
- Assicurati che l'orologio del server sia sincronizzato (TOTP si basa sul tempo)
- Il codice è valido solo per 30 secondi, generane uno nuovo
- Usa i codici di backup se l'app autenticatore non è disponibile
- Recupero account disponibile tramite email registrata
Implementa l'Autenticazione Sicura Oggi
Smart Money API supporta autenticazione di livello enterprise con OAuth 2.0, JWT, MFA e integrazione SAML. Proteggi la tua integrazione API con le migliori pratiche del settore.
Visualizza Piani Enterprise
Hai bisogno di SAML, whitelist IP o supporto dedicato? Contatta il nostro team di vendita.