Autenticación
Toda petición a la API se autentica con tu API Key enviada en el header apikey. Aquí generas tu llave, la usas de forma segura y entiendes los límites de acceso.
Obtén tu API Key
Abre Integraciones
En el menú del panel entra a la sección Integraciones, donde vive tu API Key.
Genera y copia tu llave
Copia la API Key y guárdala en un lugar seguro. Trátala como una contraseña: da acceso completo a tu cuenta y a tu saldo.
Autenticar peticiones
La API usa un esquema de API Key. Envía tu llave en el header apikey en cada petición. No se usa Authorization: Bearer ni tokens OAuth.
curl -X GET https://api.smsmasivos.com.mx/credits/consult \
-H "apikey: TU_API_KEY"Verifica que tu llave funciona consultando tu saldo. Una respuesta 200 con "success": true confirma que estás autenticado:
{ "success": true, "credits": 1500, "code": "credit_01" }Si la llave falta, es inválida o la cuenta está deshabilitada, la API responde 401:
{
"success": false,
"message": "API Key inválida o no existe.",
"status": 401,
"code": "auth_05"
}Nunca expongas tu API Key en código del lado del cliente (navegador o app móvil). Cualquiera que la vea puede gastar tu saldo. Llama a la API siempre desde tu backend.
Lista blanca de IPs
Puedes restringir el acceso de tu API Key a un conjunto de direcciones IP autorizadas desde el panel. Si una petición llega desde una IP que no está en la lista, la API responde 403:
{
"success": false,
"message": "La dirección IP no está autorizada para acceder.",
"status": 403,
"code": "auth_04"
}Recomendado para producción: agrega solo las IPs de tus servidores. Así, aunque tu llave se filtre, no podrá usarse desde otro lugar.
Rate limits
| Entorno | Límite |
|---|---|
| Producción | 100 mensajes por segundo |
| Sandbox | 100 mensajes por día |
Al exceder el límite, la API responde 429 con el código rate_01. Implementa reintentos con backoff exponencial cuando lo recibas.
Modo sandbox
Prueba tus integraciones sin gastar créditos ni enviar mensajes reales. Agrega sandbox: 1 al cuerpo de la petición en los endpoints que lo soportan (por ejemplo /sms/send). El request se valida y responde igual que en producción, pero no consume saldo ni entrega el mensaje.
Para OTP en pruebas, usa showcode: 1 en /otp/send para recibir el código generado dentro de la respuesta y así automatizar tus tests.
Buenas prácticas de seguridad
- Guarda la llave en una variable de entorno (
SMSMASIVOS_API_KEY), nunca en el código ni en el control de versiones. - Restringe el acceso con la lista blanca de IPs.
- Rota tu API Key desde el panel si sospechas que se filtró.
- Usa subcuentas para aislar entornos o clientes con su propia llave y saldo. Consulta Subcuentas en el API Reference.
Ya tienes tu API Key y sabes autenticarte. Sigue con la Guía rápida para tu primer envío.