Documentation de l'API
Advanced Authentication Patterns — OAuth 2.0, JWT, Key Rotation
Maîtrisez les mécanismes d'authentification sophistiqués pour intégrer Smart Money API dans des environnements d'entreprise. Apprenez les flux OAuth 2.0, les modèles de jetons JWT, la rotation sécurisée des clés et la mise en œuvre de l'authentification multifacteur.
Publié le 21 mars 2026
•
18 min de lecture
•
Avancé
Aperçu de l'authentification
L'API Smart Money prend en charge plusieurs méthodes d'authentification conçues pour s'adapter à différentes architectures d'applications, exigences de sécurité et politiques organisationnelles. Comprendre ces modèles garantit que votre intégration est à la fois sécurisée et performante.
L'authentification dans l'API Smart Money fonctionne sur trois couches principales :
- Clés API — Authentification simple par jeton porteur pour le développement et les intégrations directes
- Jetons JWT — Jetons sans état, signés cryptographiquement pour les systèmes distribués et les microservices
- OAuth 2.0 — Cadre d'autorisation déléguée pour les intégrations tierces et les applications SaaS
Principe de sécurité : Ne jamais exposer les informations d'authentification dans le code client, les journaux, le contrôle de version ou les messages d'erreur. Mettez en œuvre une rotation des identifiants selon un calendrier et immédiatement en cas de compromission.
Chaque méthode présente des avantages distincts. Les clés API fonctionnent mieux pour les communications entre backends où le stockage des identifiants est contrôlé. Les jetons JWT excellent dans les architectures distribuées où aucun état partagé n'est disponible. OAuth 2.0 fournit un accès délégué par l'utilisateur pour les applications tierces.
Authentification par clé API
Les clés API sont le mécanisme d'authentification le plus simple—ce sont des chaînes aléatoires générées pour votre compte qui identifient votre application auprès de l'API Smart Money. Chaque requête doit inclure votre clé API, soit dans un en-tête, soit en tant que paramètre de requête.
Clé API basée sur les en-têtes
L'approche recommandée consiste à passer votre clé API dans l'en-tête Authorization en utilisant le schéma Bearer :
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"
Clé API en tant que paramètre de requête
Pour les connexions WebSocket ou lorsque les en-têtes ne peuvent pas être modifiés, passez la clé API en tant que paramètre de requête :
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// Établit un flux WebSocket authentifié
Caractéristiques de la clé API
| Propriété |
Description |
| Format |
Chaîne hexadécimale de 128 caractères préfixée par sk_test_ ou sk_live_ |
| Portée |
Hérite de toutes les permissions du compte qui l'a créée |
| Expiration |
N'expire jamais automatiquement ; doit être renouvelée manuellement |
| Rotation |
Générez une nouvelle clé, migrez le trafic, puis désactivez l'ancienne clé |
| Limites de débit |
Partagées sur toutes les requêtes utilisant la même clé |
Pratiques de sécurité pour les clés API
- Variables d'environnement — Stockez les clés dans des fichiers .env (non inclus dans le contrôle de version) et chargez-les au moment de l'exécution
- Systèmes de coffre-fort — Utilisez HashiCorp Vault, AWS Secrets Manager ou Azure Key Vault en production
- Clés séparées — Maintenez des clés de test et de production distinctes ; faites tourner fréquemment les clés de test
- Portée minimale — Créez des clés distinctes pour différentes intégrations lorsque possible
- Journalisation d'audit — Enregistrez tous les événements de création et d'utilisation de clés API
Obtenez votre clé API en 30 secondes
Prêt à développer ? Obtenez une clé API gratuite (200 appels/jour, sans carte) et commencez à récupérer des données en direct sur les baleines, le financement et la blockchain.
Obtenez votre clé API →Modèle de jeton porteur
Les jetons porteurs étendent le concept simple de clé API en ajoutant du contexte, une expiration et des mécanismes de rafraîchissement. Ils sont idéaux pour les applications nécessitant une gestion programmatique des identifiants.
Obtention de jetons porteurs
Échangez votre clé API et votre secret contre un jeton porteur valable 24 heures :
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 de réponse du jeton
Le point de terminaison renvoie un jeton porteur avec des métadonnées :
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}
Utilisation des jetons porteurs
Incluez le jeton dans l'en-tête Authorization pour toutes les requêtes ultérieures :
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Flux de rafraîchissement du jeton
Lorsqu'un jeton approche de son expiration, utilisez le jeton de rafraîchissement pour en obtenir un nouveau sans avoir besoin de votre secret API :
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'
Implémentation OAuth 2.0
OAuth 2.0 permet aux utilisateurs d'accorder aux applications l'accès à leurs comptes Smart Money API sans partager leurs identifiants. Ceci est essentiel pour les plateformes SaaS, les intégrations tierces et les applications multi-locataires.
Flux de code d'autorisation OAuth 2.0
Le flux standard pour les applications web :
- L'utilisateur initie la connexion — L'utilisateur clique sur "Se connecter avec Smart Money API"
- Redirection vers le serveur d'autorisation — Votre application redirige l'utilisateur vers le point de terminaison d'autorisation de Smart Money
- L'utilisateur accorde la permission — L'utilisateur examine les portées demandées et accorde l'accès
- Code d'autorisation retourné — L'utilisateur est redirigé avec un code d'autorisation
- Échange du code contre un jeton — Le backend échange le code contre un jeton d'accès (le code n'est jamais exposé au frontend)
- Stockez le jeton — Stockez le refresh token de manière sécurisée ; utilisez le access token pour les appels API
Étape 1 : Rediriger l'utilisateur vers le point de terminaison d'autorisation
// URL pour rediriger l'utilisateur
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();
Étape 2 : Gérer le callback et échanger le code
// Le backend gère la route /callback
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// Vérifier le paramètre state
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// Échanger le code contre un 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();
// Stockez les tokens de manière sécurisée
Scopes OAuth
Demandez uniquement les scopes dont votre application a besoin. Smart Money API définit ces scopes :
| Scope |
Description |
| whales |
Accès au suivi des portefeuilles de baleines et aux métriques d'accumulation |
| derivatives |
Accès aux données des futures, perpétuels et taux de financement |
| onchain |
Accès aux flux de transactions on-chain et aux analyses |
| alerts |
Créer et gérer des alertes webhook |
| offline |
Accès aux refresh tokens pour obtenir de nouveaux access tokens hors ligne |
Gestion des Tokens JWT
Les JWT (JSON Web Tokens) fournissent une authentification sans état—le serveur n'a pas besoin de stocker des données de session. Smart Money API utilise RS256 (Signature RSA avec SHA-256) pour la signature des tokens, permettant la vérification sans contacter l'API.
Structure JWT
Les tokens JWT sont composés de trois parties séparées par des points :
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// HEADER.PAYLOAD.SIGNATURE
En-tête JWT
L'en-tête identifie l'algorithme et le type de token :
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}
Claims du Payload JWT
Le payload contient des claims (déclarations sur l'utilisateur/l'application) :
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}
Vérification des Signatures JWT
Téléchargez la clé publique de Smart Money et vérifiez les tokens avant de les accepter :
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Obtenez la clé publique de Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// Vérifiez le token
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// Le token est valide, utilisez les claims décodés
} catch (err) {
// Token invalide ou expiré
}
Stratégie de Rotation des Clés
La rotation régulière des clés est essentielle pour maintenir la sécurité. Même avec des pratiques de sécurité parfaites, supposez que les clés peuvent être compromises et mettez en place une rotation systématique.
Fréquence de Rotation
Smart Money recommande différents calendriers de rotation en fonction du type de clé et de son utilisation :
| Type de Clé |
Rotation Recommandée |
Rotation Minimale |
| Clés API de Test |
Mensuelle |
Trimestrielle |
| Clés API de Production |
Trimestrielle |
Annuelle |
| Refresh Tokens OAuth |
Automatique (après 90 jours) |
Manuelle (après 180 jours) |
| Clés de Compte de Service |
Semestrielle |
Annuelle |
Processus de Rotation Sans Temps d'Arrêt
Faites tourner les clés sans interrompre le service :
- Générer une Nouvelle Clé — Créez une nouvelle clé API via le tableau de bord ou l'API
- Déployer la Nouvelle Clé — Mettez à jour les secrets de l'application en staging, testez minutieusement
- Déploiement Progressif — Déployez sur 10% des serveurs, surveillez les erreurs
- Déploiement complet — Déployer sur les serveurs restants
- Vérifier le trafic — Confirmer que toutes les requêtes utilisent la nouvelle clé
- Désactiver l'ancienne clé — Marquer l'ancienne clé comme inactive mais ne pas la supprimer immédiatement
- Supprimer l'ancienne clé — Après 48 heures sans erreur, supprimer définitivement
Rotation d'urgence des clés
Si vous suspectez qu'une clé est compromise :
// Action immédiate : Désactiver la clé compromise
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// Générer immédiatement une clé de remplacement
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "Clé de remplacement d'urgence"
}'
Rotation automatisée dans Kubernetes
Utilisez Kubernetes Secrets et des opérateurs pour une rotation automatique :
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # Hebdomadaire le dimanche
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest
Authentification multifacteur (MFA)
Pour les comptes accédant aux données de production, le MFA ajoute une couche de sécurité supplémentaire en exigeant un second facteur au-delà des simples identifiants.
Méthodes MFA prises en charge
- TOTP (Mot de passe à usage unique basé sur le temps) — Applications comme Google Authenticator, Authy
- WebAuthn/FIDO2 — Clés de sécurité matérielles, biométrie
- Codes SMS à usage unique — Moins sécurisés mais universellement pris en charge
- Confirmation par email — Codes de confirmation envoyés à l'email enregistré
Activation du TOTP pour l'accès au compte
// Étape 1 : Demander la configuration du MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// La réponse inclut l'URL du QR code
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}
MFA lors des opérations API
Certaines opérations peuvent nécessiter une confirmation MFA même après authentification :
// Tentative d'opération sensible (rotation de clé)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// Réponse : MFA requis
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// Nouvelle tentative avec un code TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"
Bonnes pratiques de sécurité
L'authentification n'est aussi forte que son implémentation. Suivez ces pratiques pour maintenir la sécurité :
Gestion des secrets
- Ne jamais commettre de secrets dans le contrôle de version — Utiliser des fichiers .env avec .gitignore
- Utiliser des variables d'environnement — Charger depuis des systèmes sécurisés de gestion des secrets
- Scanner les dépôts — Utiliser des outils comme TruffleHog, detect-secrets pour trouver les clés exposées
- Auditer les journaux d'accès — Surveiller qui a accédé aux secrets et quand
Sécurité du transport
- Toujours utiliser HTTPS — Ne jamais envoyer d'identifiants via des connexions non chiffrées
- Vérifier les certificats SSL — Ne pas désactiver la validation des certificats en production
- Utiliser l'épinglage de certificat — Pour les applications mobiles, prévenir les attaques MITM
- Imposer TLS 1.2+ — Désactiver les protocoles plus anciens
Gestion des identifiants
- Hacher les secrets — Stocker des hachages bcrypt ou Argon2, jamais en clair
- Minimiser la durée de vie — Garder les identifiants en mémoire seulement le temps nécessaire
- Effacer les données sensibles — Réécrire explicitement les identifiants après utilisation
- Utiliser des bibliothèques sécurisées — Ne pas implémenter la cryptographie soi-même
Journalisation et surveillance
- Ne jamais journaliser les identifiants — Masquer les clés dans les journaux, utiliser le masquage des logs
- Journaliser les événements d'authentification — Suivre les tentatives de connexion réussies et échouées
- Surveiller les anomalies — Alerter en cas de modèles d'accès inhabituels
- Auditer l'utilisation des clés — Suivre quelles clés ont accédé à quelles données
Modèles d'authentification d'entreprise
Les grandes organisations nécessitent souvent des contrôles de sécurité supplémentaires et des capacités de conformité.
Intégration SAML 2.0
Pour les clients professionnels, Smart Money API prend en charge l'intégration SAML 2.0 avec le fournisseur d'identité de votre organisation (Okta, Azure AD, etc.) :
- Authentification unique (SSO) — Les utilisateurs s'authentifient via votre IdP d'entreprise
- Approvisionnement automatique — Créer/désactiver des comptes en fonction de l'appartenance à un groupe
- Application — Exiger SAML pour tous les accès utilisateur
Liste blanche d'IP
Restreindre l'accès API à des adresses IP ou plages CIDR spécifiques :
// Ajouter une IP à la liste blanche
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "Serveurs de production"
}'
Journalisation d'audit et conformité
Les plans entreprise incluent des journaux d'audit complets pour la conformité :
| Événement |
Données enregistrées |
| Authentification |
Utilisateur, horodatage, succès/échec, IP, statut MFA |
| Opérations sur les clés |
ID de clé, action, initiateur, horodatage |
| Modifications de compte |
Élément modifié, auteur, horodatage, valeurs avant/après |
| Accès aux données |
Utilisateur, endpoint, portées, horodatage, nombre d'enregistrements |
Dépannage des problèmes d'authentification
Erreur de clé API invalide
Problème : Réception de "401 Unauthorized - Invalid API Key"
Solutions :
- Vérifier le format de la clé (doit commencer par sk_test_ ou sk_live_)
- Vérifier les espaces avant/après dans la clé
- Confirmer que la clé n'a pas été désactivée ou renouvelée
- Vérifier que vous utilisez le bon environnement (clé test pour test, live pour production)
- Vérifier que les permissions de la clé API correspondent aux exigences de l'endpoint
Erreur de token expiré
Problème : Token porteur expiré, requêtes échouant
Solutions :
- Utiliser le token de rafraîchissement pour obtenir un nouveau token d'accès
- Implémenter un rafraîchissement automatique 5 minutes avant expiration
- Stocker le token de rafraîchissement de manière sécurisée (pas dans localStorage pour les SPA)
- Gérer les réponses 401 en tentant le flux de rafraîchissement
Erreurs CORS/Preflight
Problème : Le navigateur bloque les requêtes avec une erreur CORS
Solutions :
- Les appels API depuis les navigateurs doivent provenir d'origines autorisées
- Ajoutez votre domaine via le tableau de bord : Paramètres → Origines CORS
- Le navigateur envoie automatiquement une requête OPTIONS preflight
- Pour le développement, utilisez localhost:3000 ou similaire
Défi MFA non complété
Problème : Les opérations nécessitant un MFA échouent malgré un code correct
Solutions :
- Vérifier que l'horloge du serveur est synchronisée (TOTP dépend du temps)
- Le code n'est valable que 30 secondes, générez-en un nouveau
- Utilisez les codes de secours si l'appli d'authentification est indisponible
- Récupération de compte disponible via l'email enregistré
Implémentez une authentification sécurisée dès aujourd'hui
Smart Money API prend en charge une authentification de niveau entreprise avec OAuth 2.0, JWT, MFA et intégration SAML. Sécurisez votre intégration API avec les meilleures pratiques du secteur.
Voir les plans entreprise
Besoin de SAML, de liste blanche IP ou d'un support dédié ? Contactez notre équipe commerciale.