1. Autenticación, Generación de Claves y Controles de Seguridad
Cada nodo Apium Cloud OS expone su plano de control bajo una ruta de consola aislada (/<console>/api/v1/...). Las solicitudes aceptan credenciales mediante X-API-Key: apm_... o Authorization: Bearer apm_....
- Generación de Claves con Entropía Híbrida: Al emitir una clave en la interfaz, el navegador recopila coordenadas y tiempos de movimiento del ratón (
client_entropy) mezclados concrypto.getRandomValues. El servidor combina esa carga con dos cadenas CSPRNG de 32 caracteres y una marca de tiempo en nanosegundos mediante SHA-256, produciendo un tokenapm_<48 base62>. - Texto Plano Único y Almacenamiento con Hash: El token
apm_...sin procesar se muestra exactamente una vez al crearse. Solo su resumen SHA-256 se persiste en el almacénapi_keys. - Barreras de Red y Vida Útil: Cada clave admite una lista blanca de IPs (
allowed_ips) y una marca de tiempo de expiración automática (expires_at). - Pista de Auditoría y OpenAPI: Cada llamada a la API se registra en el log de auditoría (
GET /api/v1/api-audit), y el nodo exporta una especificación OpenAPI legible por máquina (apium-cloud-os-openapi.json) para generación de SDKs.
2. Matriz de Alcances RBAC y Niveles de Licencia
En lugar de tokens de administrador todo o nada, Apium Cloud OS aplica el principio de mínimo privilegio mediante alcances separados por comas. En la edición gratuita Lite, solo se permite el acceso read; full y todos los alcances de escritura requieren Pro, Ultra o Extra.
Alcances de Clave API y Perfiles de Mínimo Privilegio
Control de AccesoCombina alcances globales o a nivel de recurso para aislar bots de facturación, monitores SRE y automatización de RRHH.
| Alcance / Patrón | Nivel de Acceso | Perfil Operativo de Clave Típico |
|---|---|---|
| full | Lectura y escritura sin restricciones en todos los dominios (Pro/Ultra/Extra) | Orquestador maestro o controlador IaC dedicado |
| read | Solo lectura global en recursos (excluyendo /system/config) | Observador centralizado de flota o panel BI externo |
| users:read / users:write | Leer cuentas y sesiones / crear, extender, revocar, expulsar y ops masivas | Bots de facturación Telegram y SaaS, onboarding HR/IAM |
| groups:read / groups:write | Inspeccionar grupos de usuarios / asignar y modificar políticas de grupo | Automatización de acceso corporativo por departamento |
| plans:read / plans:write | Listar planes tarifarios / crear/eliminar planes y aplicar shaper de tráfico | Sincronización de tarifas comerciales y motor de políticas de banda |
| webhooks:read / webhooks:write | Listar destinos webhook / registrar o eliminar endpoints HMAC | Aprovisionamiento automatizado de bus de eventos por inquilino |
| monitoring:read | Acceso a /overview, /health, /metrics, /sessions, /logs, /api-audit | Scrapers Prometheus, Grafana, recolectores SIEM y SOC |
| system:read / system:write | Estado del sistema / modo cascada, upstreams, servicios y modo de seguridad | Automatización de failover SRE y scripts de ciclo de vida de servicios |
3. Mapa Completo de Endpoints en 7 Dominios de Control
Todas las rutas administrativas residen bajo /<console>/api/v1 y cubren toda la superficie operativa del nodo:
Endpoints Agrupados por Dominio Funcional
Superficie APICada subsistema gestionado en la interfaz web está expuesto para automatización API determinista.
| Dominio | Endpoints Clave | Capacidades |
|---|---|---|
| Usuarios y Ciclo Masivo | GET/POST /users, GET /users/generate, POST /users/bulk-create, POST /users/bulk-extend | Crear cuentas, aprovisionar flotas por lotes y extender cuotas o TTLs masivamente |
| Control por Usuario | GET /users/:id/config, POST /users/:id/extend|revoke|restore|reset-traffic|rotate-token|kick, PUT /users/:id/group|expiration|restrictions, GET /users/:id/sessions | Obtener configs de cliente, rotar tokens, expulsar sesiones activas y ajustar límites por usuario |
| Planes y Shaper | GET/POST /plans, DELETE /plans/:id, POST /shaper/apply | Gestionar plantillas de tarifas y aplicar reglas de ancho de banda/shaper en vivo |
| Cascada y Upstreams | PUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-traffic | Cambiar modos de enrutamiento en cascada, sondear nodos de salida, alternar upstreams y reiniciar contadores |
| Monitoreo y Auditoría | GET /overview, GET /health, GET /metrics, GET /sessions, POST /sessions/:id/kick, GET/DELETE /logs, POST /logs/simulate, GET /api-audit | Comprobaciones de salud, telemetría Prometheus, terminación de sesiones en vivo y logs de auditoría API |
| Webhooks y Claves | GET/POST /webhooks, DELETE /webhooks/:id, GET/POST /api-keys, DELETE /api-keys/:id | Ciclo de vida programático para suscriptores webhook HMAC y claves API con alcance |
| Servicios, Seguridad y Licencia | POST /services/toggle|restart|update-adblock|unban-ip|clear-auth-logs, PUT /settings/security-mode, GET /license/status, POST /license/activate | Control de demonios, desbloqueo de IPs en Fail2ban, actualizaciones AdBlock y activación de licencia |
| Corporate Gateway | GET /enterprise/overview, POST /enterprise/users/:id/toggle, .../enterprise/users/:id, .../enterprise/gateways/:id | Plano de control dedicado para usuarios de Corporate Gateway y nodos de puerta de enlace |
4. Ejemplos Prácticos de Solicitudes y Eventos
A. Aprovisionamiento y Extensión Masiva de Usuarios
Crea cuentas vinculadas a un plan tarifario (plan_id), ejecuta aprovisionamiento por lotes o extiende suscripciones con restauración automática (auto_restore: true) sin reiniciar los núcleos de transporte:
curl -X POST -H "X-API-Key: apm_..." \
-H "Content-Type: application/json" \
-d '{"username":"client_9042","plan_id":1}' \
https://node.apium.cloud/<console>/api/v1/users
curl -X POST -H "Authorization: Bearer apm_..." \
-H "Content-Type: application/json" \
-d '{"add_days":30,"add_quota_gb":100,"auto_restore":true}' \
https://node.apium.cloud/<console>/api/v1/users/42/extend
B. Endpoint Público de Suscripción (Cabeceras Estándar de Cliente)
Aplicaciones cliente como v2rayNG, Nekobox, Streisand y Hiddify obtienen una única URL tokenizada que devuelve perfiles Base64 junto con cabeceras estándar de cuota y expiración:
GET /<console>/api/v1/subscriptions/<sub_token>
< HTTP/1.1 200 OK
< Profile-Title: Apium Cloud OS
< Profile-Update-Interval: 12
< Subscription-Userinfo: upload=104857600; download=2147483648; total=107374182400; expire=1798761600
C. Webhooks Firmados con HMAC-SHA256
En lugar de consultar el nodo cada pocos segundos, configura tu backend de facturación o CRM para recibir eventos push en tiempo real verificados por X-Apium-Signature:
POST https://billing.example.com/webhooks/apium
X-Apium-Event: user.created
X-Apium-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
{
"event": "user.created",
"timestamp": "2026-11-14T12:30:00Z",
"data": { "user": { "id": 42, "username": "client_9042", "protocol": "hysteria2" } }
}
D. Métricas Prometheus (GET /api/v1/metrics)
Conecta tu flota directamente a Prometheus y Grafana con una clave monitoring:read para rastrear sesiones activas, recuento de usuarios y RTTs de cascada upstream:
# TYPE apium_active_sessions gauge
apium_active_sessions 1248
# TYPE apium_users_total gauge
apium_users_total{status="active"} 3410
# TYPE apium_upstream_latency_ms gauge
apium_upstream_latency_ms{id="1",name="NL-AMS-01"} 18
5. Escenarios de Integración en el Mundo Real
Dónde Destaca la API de Apium Cloud OS
Patrones de IntegraciónArquitecturas de producción comunes construidas sobre la REST API de Apium, Claves RBAC, Webhooks y Prometheus.
| Escenario | Primitivas API Utilizadas | Beneficio Operativo |
|---|---|---|
| Bots de Telegram y Facturación SaaS | Clave users:write + POST /users, /users/bulk-create, /extend, Subscriptions + Webhooks | Entrega instantánea de clave tras el pago, renovaciones automatizadas, cero trabajo manual de admin |
| Onboarding Corporativo HR / IAM | users:write + groups:write + POST /users/:id/kick y /enterprise/... | Acceso VPN automático al contratar y revocación instantánea de sesión al dar de baja |
| SRE y Monitoreo de Flota | Clave monitoring:read + GET /metrics, /health, /api-audit + lista blanca IP | Paneles Grafana y alertas sin exponer permisos de escritura |
| Automatización de Cascada y Shaper | system:write + plans:write + PUT /cascade/mode, POST /upstreams/check, POST /shaper/apply | Failover dinámico entre países de salida y aplicación automatizada de ancho de banda |