Documentación de la API
Patrones Avanzados de Autenticación — OAuth 2.0, JWT, Rotación de Claves
Domina mecanismos sofisticados de autenticación para integrar Smart Money API en entornos empresariales. Aprende flujos de OAuth 2.0, patrones de tokens JWT, rotación segura de claves e implementación de autenticación multifactor.
Publicado el 21 de marzo de 2026
•
18 minutos de lectura
•
Avanzado
Resumen de Autenticación
La API de Smart Money admite múltiples métodos de autenticación diseñados para adaptarse a diferentes arquitecturas de aplicaciones, requisitos de seguridad y políticas organizacionales. Comprender estos patrones asegura que tu integración sea segura y eficiente.
La autenticación en la API de Smart Money opera en tres capas principales:
- Claves API — Autenticación simple con token bearer para desarrollo e integraciones directas
- Tokens JWT — Tokens sin estado y firmados criptográficamente para sistemas distribuidos y microservicios
- OAuth 2.0 — Marco de autorización delegada para integraciones de terceros y aplicaciones SaaS
Principio de Seguridad: Nunca expongas credenciales de autenticación en código del lado del cliente, registros, control de versiones o mensajes de error. Implementa la rotación de credenciales según un cronograma e inmediatamente en caso de compromiso.
Cada método tiene ventajas distintas. Las claves API funcionan mejor para la comunicación backend-to-backend donde el almacenamiento de credenciales está controlado. Los tokens JWT destacan en arquitecturas distribuidas donde no hay estado compartido. OAuth 2.0 proporciona acceso delegado por el usuario para aplicaciones de terceros.
Autenticación con Clave API
Las claves API son el mecanismo de autenticación más simple: son cadenas aleatorias generadas para tu cuenta que identifican tu aplicación ante la API de Smart Money. Cada solicitud debe incluir tu clave API, ya sea como encabezado o parámetro de consulta.
Clave API Basada en Encabezado
El enfoque recomendado es pasar tu clave API en el encabezado Authorization usando el esquema Bearer:
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"
Clave API como Parámetro de Consulta
Para conexiones WebSocket o cuando no se pueden modificar los encabezados, pasa la clave API como parámetro de consulta:
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// Establece un flujo WebSocket autenticado
Características de la Clave API
| Propiedad |
Descripción |
| Formato |
Cadena hexadecimal de 128 caracteres con prefijo sk_test_ o sk_live_ |
| Alcance |
Hereda todos los permisos de la cuenta que la creó |
| Expiración |
No expira automáticamente; debe rotarse manualmente |
| Rotación |
Genera una nueva clave, migra el tráfico y luego desactiva la clave antigua |
| Límites de Tasa |
Compartidos en todas las solicitudes que usan la misma clave |
Prácticas de Seguridad de Claves API
- Variables de Entorno — Almacena las claves en archivos .env (no comprometidos en el control de versiones) y cárgalas en tiempo de ejecución
- Sistemas de Bóveda — Usa HashiCorp Vault, AWS Secrets Manager o Azure Key Vault en producción
- Claves Separadas — Mantén claves de prueba y producción separadas; rota las claves de prueba con frecuencia
- Alcance Mínimo — Crea claves separadas para diferentes integraciones cuando sea posible
- Registro de Auditoría — Registra todos los eventos de creación y uso de claves API
Obtén tu clave API en 30 segundos
¿Listo para construir? Obtén una clave API gratuita (200 llamadas/día, sin tarjeta) y comienza a obtener datos en vivo de ballenas, financiamiento y cadena de bloques.
Obtén tu clave API →Patrón de Token Bearer
Los tokens bearer extienden el concepto simple de clave API al agregar contexto, expiración y mecanismos de actualización. Son ideales para aplicaciones que necesitan gestión programática de credenciales.
Obtención de Tokens Bearer
Intercambia tu clave API y secreto por un token bearer válido por 24 horas:
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 de Respuesta del Token
El endpoint devuelve un token bearer con metadatos:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}
Uso de Tokens Bearer
Incluye el token en el encabezado Authorization para todas las solicitudes posteriores:
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Flujo de Actualización de Token
Cuando un token está cerca de expirar, usa el token de actualización para obtener uno nuevo sin requerir tu secreto API:
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'
Implementación de OAuth 2.0
OAuth 2.0 permite a los usuarios otorgar acceso a sus cuentas de Smart Money API a aplicaciones sin compartir credenciales. Esto es esencial para plataformas SaaS, integraciones de terceros y aplicaciones multiinquilino.
Flujo de Código de Autorización de OAuth 2.0
El flujo estándar para aplicaciones web:
- El Usuario Inicia el Inicio de Sesión — El usuario hace clic en "Conectar con Smart Money API"
- Redirección al Servidor de Autorización — Tu aplicación redirige al usuario al endpoint de autorización de Smart Money
- El Usuario Otorga Permiso — El usuario revisa los alcances solicitados y otorga acceso
- Código de Autorización Devuelto — El usuario es redirigido de vuelta con el código de autorización
- Intercambio de Código por Token — El backend intercambia el código por un token de acceso (el código nunca se expone al frontend)
- Almacenamiento del Token — Almacena el token de actualización de forma segura; usa el token de acceso para las llamadas API
Paso 1: Redirigir al usuario al punto de autorización
// URL para redirigir al usuario
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();
Paso 2: Manejar la devolución de llamada e intercambiar el código
// El backend maneja la ruta /callback
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// Verificar el parámetro state
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// Intercambiar el código por 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();
// Almacenar los tokens de forma segura
Ámbitos de OAuth
Solicita solo los ámbitos que tu aplicación necesita. Smart Money API define estos ámbitos:
| Ámbito |
Descripción |
| whales |
Acceso al seguimiento de carteras de ballenas y métricas de acumulación |
| derivatives |
Acceso a datos de futuros, perpetuos y tasas de financiación |
| onchain |
Acceso a flujos de transacciones y análisis en cadena |
| alerts |
Crear y gestionar alertas mediante webhooks |
| offline |
Acceso a tokens de actualización para obtener nuevos tokens de acceso sin conexión |
Gestión de Tokens JWT
Los JWT (JSON Web Tokens) proporcionan autenticación sin estado: el servidor no necesita almacenar datos de sesión. Smart Money API utiliza RS256 (Firma RSA con SHA-256) para la firma de tokens, permitiendo la verificación sin contactar con la API.
Estructura del JWT
Los tokens JWT constan de tres partes separadas por puntos:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// CABECERA.PAYLOAD.FIRMA
Cabecera del JWT
La cabecera identifica el algoritmo y el tipo de token:
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}
Reclamaciones del Payload del JWT
El payload contiene reclamaciones (declaraciones sobre el usuario/aplicación):
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}
Verificación de Firmas JWT
Descarga la clave pública de Smart Money y verifica los tokens antes de aceptarlos:
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Obtener la clave pública de Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// Verificar el token
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// El token es válido, usa las reclamaciones decodificadas
} catch (err) {
// Token inválido o expirado
}
Estrategia de Rotación de Claves
La rotación regular de claves es crucial para mantener la seguridad. Incluso con prácticas de seguridad perfectas, asume que las claves pueden verse comprometidas e implementa una rotación sistemática.
Frecuencia de Rotación
Smart Money recomienda diferentes cronogramas de rotación según el tipo de clave y su uso:
| Tipo de Clave |
Rotación Recomendada |
Rotación Mínima |
| Claves API de Prueba |
Mensual |
Trimestral |
| Claves API de Producción |
Trimestral |
Anual |
| Tokens de Actualización de OAuth |
Automática (después de 90 días) |
Manual (después de 180 días) |
| Claves de Cuentas de Servicio |
Semestral |
Anual |
Proceso de Rotación sin Tiempo de Inactividad
Rota las claves sin interrumpir el servicio:
- Generar Nueva Clave — Crear una nueva clave API a través del panel o la API
- Implementar Nueva Clave — Actualizar los secretos de la aplicación en staging, probar exhaustivamente
- Implementación Gradual — Implementar en el 10% de los servidores, monitorear errores
- Implementación Completa — Desplegar en los servidores restantes
- Verificar Tráfico — Confirmar que todas las solicitudes usen la nueva clave
- Desactivar Clave Antigua — Marcar la clave antigua como inactiva pero no eliminarla inmediatamente
- Eliminar Clave Antigua — Después de 48 horas sin errores, eliminar permanentemente
Rotación de Clave de Emergencia
Si sospechas que una clave está comprometida:
// Acción inmediata: Desactivar clave comprometida
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// Generar clave de reemplazo inmediatamente
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "Clave de Reemplazo de Emergencia"
}'
Rotación Automatizada en Kubernetes
Usa Secrets y operadores de Kubernetes para rotación automática:
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # Semanalmente los domingos
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest
Autenticación Multifactor (MFA)
Para cuentas que acceden a datos de producción, MFA proporciona una capa adicional de seguridad al requerir un segundo factor además de las credenciales.
Métodos MFA Soportados
- TOTP (Contraseña de Un Solo Uso Basada en Tiempo) — Aplicaciones como Google Authenticator, Authy
- WebAuthn/FIDO2 — Claves de seguridad físicas, biometría
- Códigos de Un Solo Uso por SMS — Menos seguros pero universalmente soportados
- Confirmación por Correo Electrónico — Códigos de confirmación enviados al correo registrado
Habilitar TOTP para Acceso a la Cuenta
// Paso 1: Solicitar configuración de MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// La respuesta incluye URL de código QR
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}
MFA Durante Operaciones de API
Algunas operaciones pueden requerir confirmación MFA incluso después de la autenticación:
// Intentando operación sensible (rotación de clave)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// Respuesta: MFA requerido
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// Reintentar con código TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"
Mejores Prácticas de Seguridad
La autenticación es tan fuerte como su implementación. Sigue estas prácticas para mantener la seguridad:
Gestión de Secretos
- Nunca guardes secretos en control de versiones — Usa archivos .env con .gitignore
- Usa variables de entorno — Carga desde sistemas seguros de gestión de secretos
- Escanea repositorios — Usa herramientas como TruffleHog, detect-secrets para encontrar claves expuestas
- Audita registros de acceso — Monitorea quién accedió a los secretos y cuándo
Seguridad en el Transporte
- Siempre usa HTTPS — Nunca envíes credenciales sobre conexiones no cifradas
- Verifica certificados SSL — No deshabilites la validación de certificados en producción
- Usa fijación de certificados — Para aplicaciones móviles, evita ataques MITM
- Exige TLS 1.2+ — Deshabilita protocolos antiguos
Manejo de Credenciales
- Hashea los secretos — Almacena hashes bcrypt o Argon2, nunca texto plano
- Minimiza el tiempo de vida — Mantén credenciales en memoria solo el tiempo necesario
- Borra datos sensibles — Sobrescribe credenciales explícitamente después de usarlas
- Usa bibliotecas seguras — No implementes criptografía tú mismo
Registro y Monitoreo
- Nunca registres credenciales — Enmascara claves en registros, usa enmascaramiento de logs
- Registra eventos de autenticación — Rastrea intentos de inicio de sesión exitosos y fallidos
- Monitorea anomalías — Alerta sobre patrones de acceso inusuales
- Audita el uso de claves — Rastrea qué claves accedieron a qué datos
Patrones de Autenticación Empresarial
Las grandes organizaciones a menudo requieren controles de seguridad adicionales y capacidades de cumplimiento.
Integración SAML 2.0
Para clientes empresariales, Smart Money API soporta integración SAML 2.0 con el proveedor de identidad de tu organización (Okta, Azure AD, etc.):
- Inicio de Sesión Único (SSO) — Los usuarios se autentican a través del IdP corporativo
- Aprovisionamiento automático — Crea/desactiva cuentas basadas en membresía de grupos
- Exigencia — Requiere SAML para todo acceso de usuario
Lista Blanca de IP
Restringir el acceso a la API a direcciones IP o rangos CIDR específicos:
// Añadir IP a la lista blanca
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "Servidores de producción"
}'
Registro de Auditoría y Cumplimiento
Los planes empresariales incluyen registros de auditoría completos para cumplimiento:
| Evento |
Datos Registrados |
| Autenticación |
Usuario, fecha y hora, éxito/fallo, IP, estado de MFA |
| Operaciones con Claves |
ID de clave, acción, iniciador, fecha y hora |
| Cambios en la Cuenta |
Qué cambió, quién lo cambió, fecha y hora, valores antes/después |
| Acceso a Datos |
Usuario, endpoint, alcances, fecha y hora, cantidad de registros |
Solución de Problemas de Autenticación
Error de Clave de API Inválida
Problema: Recibiendo "401 No Autorizado - Clave de API Inválida"
Soluciones:
- Verificar el formato de la clave (debe comenzar con sk_test_ o sk_live_)
- Comprobar espacios en blanco al inicio/final de la clave
- Confirmar que la clave no ha sido desactivada o rotada
- Verificar que estás usando el entorno correcto (clave de prueba para test, clave real para producción)
- Comprobar que los permisos de la clave de API coinciden con los requisitos del endpoint
Error de Token Expirado
Problema: Token de portador expirado, solicitudes fallando
Soluciones:
- Usar token de actualización para obtener nuevo token de acceso
- Implementar actualización automática de token 5 minutos antes de la expiración
- Almacenar token de actualización de forma segura (no en localStorage para SPAs)
- Manejar respuestas 401 intentando el flujo de token de actualización
Errores CORS/Preflight
Problema: Navegador bloqueando solicitudes con error CORS
Soluciones:
- Las llamadas a la API desde navegadores deben venir de orígenes permitidos
- Añade tu dominio en el panel: Configuración → Orígenes CORS
- El navegador envía automáticamente una solicitud OPTIONS preflight
- Para desarrollo, usa localhost:3000 o similar
Desafío MFA No se Completa
Problema: Operaciones que requieren MFA fallan incluso con código correcto
Soluciones:
- Asegurar que el reloj del servidor está sincronizado (TOTP depende del tiempo)
- El código es válido solo por 30 segundos, genera uno nuevo
- Usar códigos de respaldo si la app de autenticación no está disponible
- Recuperación de cuenta disponible vía email registrado
Implementa Autenticación Segura Hoy
Smart Money API soporta autenticación de nivel empresarial con OAuth 2.0, JWT, MFA e integración SAML. Protege tu integración de API con las mejores prácticas del sector.
Ver Planes Empresariales
¿Necesitas SAML, lista blanca de IP o soporte dedicado? Contacta a nuestro equipo de ventas.