Kuska IoT SaaS MQTT

Uso de la API REST

La API permite autenticar usuarios, administrar proyectos y dispositivos, consultar mensajes MQTT almacenados, revisar uso del plan, gestionar suscripciones y conectar el flujo de billing con PayPal. Los endpoints están pensados para dos usos principales: alimentar el dashboard web y permitir que los makers consulten su telemetría desde sistemas externos.

Base URL

La URL pública final de la API será el dominio principal de la plataforma.

https://kuska-iot.com

Autenticación

Inicia sesión para obtener un JWT. En las peticiones protegidas envía ese valor en Authorization: Bearer.

curl -X POST https://kuska-iot.com/api/auth/login \
  -H "content-type: application/json" \
  -d '{"email":"usuario@example.com","password":"tu-password"}'

{
  "token": "eyJ..."
}

Authorization: Bearer TU_TOKEN

Tokens API generados por admin

Un administrador puede crear tokens desde /admin/users. Esos tokens son JWT de larga duración y se usan igual que el token de login.

curl https://kuska-iot.com/api/messages \
  -H "Authorization: Bearer TOKEN_GENERADO"

Cuenta

POST

Registrar usuario

Crea una cuenta nueva para un maker o integrador. El usuario nace con rol user y plan Free por defecto, por lo que queda listo para entrar al dashboard y crear proyectos.

/api/auth/register

Body

{"name":"Ada Maker","email":"ada@example.com","password":"tu-password"}

POST

Iniciar sesión

Valida email y contraseña. Devuelve el JWT que se debe enviar como Bearer token en las rutas protegidas.

/api/auth/login

Body

{"email":"ada@example.com","password":"tu-password"}

Respuesta ejemplo

{"token":"eyJ..."}

POST

Cerrar sesión

Endpoint liviano para cerrar sesión desde el cliente. Actualmente confirma la operación; el token se elimina del navegador en el frontend.

/api/auth/logout

Respuesta ejemplo

{"success":true}

GET

Cuenta actual

Devuelve los datos públicos de la cuenta autenticada. Sirve para reconstruir la sesión del dashboard y saber nombre, email, rol y plan sin exponer el passwordHash.

/api/auth/me

cURL

curl https://kuska-iot.com/api/auth/me \
  -H "Authorization: Bearer TU_TOKEN"

PATCH

Actualizar perfil

Actualiza nombre y email de la cuenta autenticada.

/api/auth/profile

Body

{"name":"Ada Lovelace","email":"ada@kuska.dev"}

cURL

curl -X PATCH https://kuska-iot.com/api/auth/profile \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"Ada Lovelace","email":"ada@kuska.dev"}'

PATCH

Cambiar contraseña

Permite que el usuario autenticado cambie su contraseña. Requiere la contraseña actual y valida que la nueva tenga al menos 8 caracteres.

/api/auth/password

Body

{"currentPassword":"password-actual","newPassword":"nuevo-password-seguro"}

cURL

curl -X PATCH https://kuska-iot.com/api/auth/password \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "content-type: application/json" \
  -d '{"currentPassword":"password-actual","newPassword":"nuevo-password-seguro"}'

Proyectos

GET

Listar proyectos

Devuelve los proyectos del usuario autenticado. Es el punto de partida del dashboard para separar grupos de dispositivos y tópicos MQTT.

/api/projects

cURL

curl https://kuska-iot.com/api/projects \
  -H "Authorization: Bearer TU_TOKEN"

POST

Crear proyecto

Genera automáticamente el slug y el topic raíz MQTT del proyecto.

/api/projects

Body

{"name":"Planta piloto","description":"Sensores ESP32"}

cURL

curl -X POST https://kuska-iot.com/api/projects \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"Planta piloto","description":"Sensores ESP32"}'

GET

Consultar proyecto

Devuelve un proyecto específico del usuario autenticado. Útil para abrir una vista de detalle y cargar su configuración MQTT.

/api/projects/{id}

PATCH

Actualizar proyecto

Actualiza metadatos del proyecto, como nombre y descripción. No cambia automáticamente credenciales MQTT de dispositivos existentes.

/api/projects/{id}

Body

{"name":"Planta piloto 2","description":"Nueva descripción"}

DELETE

Eliminar proyecto

Elimina el proyecto y sus dispositivos asociados.

/api/projects/{id}

Dispositivos

POST

Crear dispositivo

La respuesta incluye la contraseña MQTT una sola vez. Respeta el límite de dispositivos del plan.

/api/projects/{projectId}/devices

Body

{"name":"ESP32 Sala 1"}

cURL

curl -X POST https://kuska-iot.com/api/projects/PROJECT_ID/devices \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"ESP32 Sala 1"}'

GET

Listar dispositivos

Lista dispositivos del usuario. Puede filtrarse por proyecto para construir paneles, tablas de administración o integraciones externas.

/api/devices | /api/devices?projectId=PROJECT_ID | /api/projects/{projectId}/devices

cURL

curl "https://kuska-iot.com/api/devices?projectId=PROJECT_ID" \
  -H "Authorization: Bearer TU_TOKEN"

GET

Consultar dispositivo

Devuelve el detalle de un dispositivo propio, incluyendo datos operativos necesarios para mostrar su estado en el dashboard.

/api/devices/{id}

PATCH

Actualizar dispositivo

Permite cambiar nombre y estado manual.

/api/devices/{id}

Body

{"name":"ESP32 Oficina","status":"online"}

DELETE

Eliminar dispositivo

Elimina un dispositivo del usuario autenticado. Debe usarse cuando el equipo deja de pertenecer al proyecto o se necesita liberar cupo del plan.

/api/devices/{id}

Mensajes MQTT

Este endpoint consulta la telemetría persistida por el worker MQTT. Devuelve hasta 50 mensajes recientes del usuario autenticado y puede filtrarse por proyecto o dispositivo. La consulta respeta la retención del plan: Free 7 días, Starter 90 días, Pro 365 días, Business 730 días y Enterprise sin límite configurado.

GET /api/messages
GET /api/messages?projectId=PROJECT_ID
GET /api/messages?projectId=PROJECT_ID&deviceId=DEVICE_ID

curl "https://kuska-iot.com/api/messages?projectId=PROJECT_ID&deviceId=DEVICE_ID" \
  -H "Authorization: Bearer TU_TOKEN"

Plan, uso y billing

GET

Uso del plan

Devuelve límites, uso del ciclo actual, porcentajes y flags para saber si puede crear dispositivos o guardar mensajes.

/api/billing/usage

Respuesta ejemplo

{
  "plan": { "id": "pro", "name": "Pro", "maxDevices": 100, "maxMessagesMonthly": 25000000 },
  "usage": { "devices": 12, "messagesThisMonth": 5300 },
  "allowed": { "createDevice": true, "storeMessage": true }
}

cURL

curl https://kuska-iot.com/api/billing/usage \
  -H "Authorization: Bearer TU_TOKEN"

GET

Suscripción actual

Devuelve el plan efectivo del usuario y, si existe, la suscripción local vinculada a PayPal.

/api/billing/subscription

cURL

curl https://kuska-iot.com/api/billing/subscription \
  -H "Authorization: Bearer TU_TOKEN"

POST

Crear checkout PayPal

Crea una suscripción PayPal para un plan pago y devuelve approvalUrl. Requiere PAYPAL_*_PLAN_ID reales en el entorno.

/api/billing/paypal/create-subscription

Body

{"plan":"pro","interval":"month"}

Respuesta ejemplo

{
  "provider": "paypal",
  "subscriptionId": "I-...",
  "status": "APPROVAL_PENDING",
  "approvalUrl": "https://www.sandbox.paypal.com/..."
}

POST

Webhook PayPal

Endpoint público para PayPal. Verifica la firma con PAYPAL_WEBHOOK_ID, guarda eventos idempotentes y actualiza users.plan cuando la suscripción se activa, suspende, cancela o expira.

/api/billing/paypal/webhook

Ejemplo con JavaScript

const token = 'TU_TOKEN'

const messages = await fetch('https://kuska-iot.com/api/messages?projectId=PROJECT_ID', {
  headers: {
    Authorization: `Bearer ${token}`
  }
}).then((response) => response.json())

console.log(messages)

Endpoints admin

Requieren usuario con rol admin. Sirven para operar la plataforma: ver métricas globales, administrar usuarios, asignar planes y emitir tokens API para cuentas registradas. No deben consumirse desde firmware ni desde dispositivos.

GET

Métricas globales

Devuelve conteos globales de usuarios, dispositivos y mensajes. Es útil para el panel administrativo y para validar crecimiento de la beta.

/api/admin/stats

GET

Listar usuarios

Devuelve usuarios registrados sin passwordHash. Permite revisar cuentas, roles, planes y datos básicos desde el dashboard admin.

/api/admin/users

PATCH

Asignar plan a usuario

Cambia manualmente el plan de un usuario. Es útil mientras no hay pasarela completamente automatizada o para soporte comercial.

/api/admin/users/{id}/plan

Body

{"plan":"pro"}

GET

Listar tokens API

Lista tokens API activos generados para usuarios registrados. No devuelve el token completo ni su hash, solo metadatos y preview.

/api/admin/tokens?userId=USER_ID

POST

Crear token API

Genera un JWT de larga duración para que un usuario consuma la API desde integraciones externas. El token completo solo aparece en la respuesta de creación.

/api/admin/tokens

Body

{"userId":"USER_ID","name":"Integración backend"}

Respuesta ejemplo

{
  "_id": "TOKEN_ID",
  "userId": "USER_ID",
  "name": "Integración backend",
  "token": "eyJ...",
  "tokenPreview": "eyJhbGciOiJI...abc123"
}

POST

Promover primer admin

Promueve una cuenta existente a admin usando ADMIN_BOOTSTRAP_KEY. Está pensado para inicializar el entorno; si la variable no existe, el endpoint queda deshabilitado.

/api/admin/bootstrap

Body

{"email":"tu-email@example.com","key":"valor-de-ADMIN_BOOTSTRAP_KEY"}

Notas de seguridad

No compartas tokens en repositorios, firmware público o capturas.
Los endpoints filtran datos por el usuario autenticado.
Los tokens generados desde admin deben tratarse como credenciales de producción.
Para producción, usa HTTPS y rota tokens comprometidos.
El plan efectivo se actualiza por webhook verificado de PayPal o por acción admin.
Los IDs PayPal de sandbox no funcionan en live y viceversa.