Autenticacion y API Keys

Como funciona la autenticacion

La API de WhatsBoost utiliza un modelo de autenticacion basado en API Keys (claves secretas). Cada solicitud HTTP que envies a cualquier endpoint de la API debe incluir un parametro llamado secret con el valor de tu API Key.

Caracteristicas de la API Key

Flujo de autenticacion

1. Tu aplicacion envia una peticion POST a un endpoint de la API (por ejemplo, /api/send/sms).
2. En el cuerpo de la peticion incluyes el parametro secret con el valor de tu API Key.
3. El servidor valida que la API Key exista, este activa y tenga los permisos necesarios para el endpoint solicitado.
4. Si la validacion es correcta, se procesa la solicitud y se devuelve una respuesta JSON.
5. Si la API Key es invalida o no tiene permisos, se devuelve un error 401 o 403 con un mensaje explicativo.

Generar tu primera API Key

Crear una API Key es el primer paso para integrar WhatsBoost en tu aplicacion. Sigue estos pasos:

Multiples API Keys para diferentes integraciones

Es una buena practica crear una API Key separada para cada integracion o servicio que conectes con WhatsBoost. Esto te permite:

• Permisos granulares: Cada key solo tiene acceso a lo que necesita. Tu CRM puede tener permisos de envio, mientras que tu dashboard de analisis solo tiene permisos de lectura.
• Rastreo independiente: Puedes monitorizar el uso de cada key por separado desde el Dashboard.
• Revocacion segura: Si una key se ve comprometida, puedes revocarla sin afectar al resto de tus integraciones.
• Rotacion escalonada: Puedes rotar keys de forma independiente segun el calendario de seguridad de cada proyecto.

Tabla completa de permisos

Cada API Key tiene un conjunto de permisos que determinan que endpoints puede utilizar. A continuacion se listan todos los permisos disponibles, agrupados por categoria.

Permisos de Envio

Permisos necesarios para enviar mensajes, codigos OTP y ejecutar comandos USSD.

Permisos de Lectura

Permisos para consultar datos, estadisticas y registros de tu cuenta.

Permisos de Creacion

Permisos para crear nuevos recursos en tu cuenta.

Permisos de Eliminacion

Permisos para eliminar recursos. Usa estos permisos con precaucion ya que las eliminaciones son irreversibles.

Ejemplos de autenticacion

A continuacion se muestran ejemplos basicos de como enviar tu API Key en una peticion a la API. Todos los ejemplos realizan una consulta al endpoint /api/get/credits para verificar que la autenticacion funciona correctamente.

curl -X POST //whatsboost.netapi/get/credits \
  -d "secret=TU_API_KEY_DE_40_CARACTERES"

<?php
$apiKey = "TU_API_KEY_DE_40_CARACTERES";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "//whatsboost.netapi/get/credits");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    "secret" => $apiKey
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

if ($httpCode === 200) {
    echo "Creditos disponibles: " . $data["data"]["credits"];
} else {
    echo "Error: " . $data["message"];
}

const apiKey = "TU_API_KEY_DE_40_CARACTERES";

const formData = new URLSearchParams();
formData.append("secret", apiKey);

const response = await fetch("//whatsboost.netapi/get/credits", {
    method: "POST",
    headers: {
        "Content-Type": "application/x-www-form-urlencoded"
    },
    body: formData
});

const data = await response.json();

if (response.ok) {
    console.log("Creditos disponibles:", data.data.credits);
} else {
    console.error("Error:", data.message);
}

import requests

api_key = "TU_API_KEY_DE_40_CARACTERES"

response = requests.post(
    "//whatsboost.netapi/get/credits",
    data={
        "secret": api_key
    }
)

data = response.json()

if response.status_code == 200:
    print(f"Creditos disponibles: {data['data']['credits']}")
else:
    print(f"Error: {data['message']}")

Respuesta exitosa

{
    "status": 200,
    "message": "Success!",
    "data": {
        "credits": 150.75
    }
}

Respuesta con API Key invalida

{
    "status": 401,
    "message": "Invalid API secret supplied!"
}

Respuesta con permisos insuficientes

{
    "status": 403,
    "message": "This API key doesn't have permission to use this endpoint!"
}

Seguridad y buenas practicas

Tu API Key es tan sensible como una contrasena. Si alguien obtiene acceso a ella, puede realizar acciones en tu nombre (enviar mensajes, leer datos, eliminar registros). Sigue estas recomendaciones para proteger tus credenciales:

Monitoriza el uso desde el Dashboard

WhatsBoost te permite ver el historial de peticiones realizadas con cada API Key desde el Dashboard. Revisa periodicamente:

• Volumen de peticiones: Un aumento inusual puede indicar un uso no autorizado.
• Endpoints accedidos: Verifica que solo se accede a los endpoints esperados.
• Errores 401/403: Multiples intentos fallidos pueden indicar que alguien esta probando keys robadas.
• Horarios de uso: Si tu integracion solo funciona en horario laboral y ves peticiones a las 3 AM, investiga.

Lista de verificacion de seguridad

Prompt para asistentes de IA

Eres un desarrollador backend experto. Necesito integrar la API de WhatsBoost
en mi proyecto. La autenticacion funciona asi:

- Todas las peticiones son POST a //whatsboost.netapi/...
- Se envia un parametro "secret" en el cuerpo (form-data o x-www-form-urlencoded)
  con el valor de la API Key (hash SHA1 de 40 caracteres).
- La API Key NO se envia como header, sino como parametro POST.
- Las respuestas son JSON con la estructura:
  {"status": CODE, "message": "...", "data": {...}}

Ayudame a:
1. Crear una clase/modulo reutilizable para mi proyecto que gestione las
   peticiones a la API de WhatsBoost.
2. Almacenar la API Key de forma segura (variables de entorno).
3. Manejar los errores (401, 403, 400, 500) con mensajes claros.
4. Implementar reintentos automaticos para errores transitorios (500, timeout).

Mi stack tecnologico es: [INDICA TU STACK AQUI]

Siguientes pasos