Formato de Clave
apm_<48 base62> (SHA-256)
Alcances RBAC
full, read + 12 Granulares
Plano de Control
7 Dominios API + /enterprise
Telemetría y Eventos
Webhooks HMAC + Prometheus

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 con crypto.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 token apm_<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én api_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 Acceso

Combina alcances globales o a nivel de recurso para aislar bots de facturación, monitores SRE y automatización de RRHH.

Alcance / PatrónNivel de AccesoPerfil Operativo de Clave Típico
fullLectura y escritura sin restricciones en todos los dominios (Pro/Ultra/Extra)Orquestador maestro o controlador IaC dedicado
readSolo lectura global en recursos (excluyendo /system/config)Observador centralizado de flota o panel BI externo
users:read / users:writeLeer cuentas y sesiones / crear, extender, revocar, expulsar y ops masivasBots de facturación Telegram y SaaS, onboarding HR/IAM
groups:read / groups:writeInspeccionar grupos de usuarios / asignar y modificar políticas de grupoAutomatización de acceso corporativo por departamento
plans:read / plans:writeListar planes tarifarios / crear/eliminar planes y aplicar shaper de tráficoSincronización de tarifas comerciales y motor de políticas de banda
webhooks:read / webhooks:writeListar destinos webhook / registrar o eliminar endpoints HMACAprovisionamiento automatizado de bus de eventos por inquilino
monitoring:readAcceso a /overview, /health, /metrics, /sessions, /logs, /api-auditScrapers Prometheus, Grafana, recolectores SIEM y SOC
system:read / system:writeEstado del sistema / modo cascada, upstreams, servicios y modo de seguridadAutomatizació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 API

Cada subsistema gestionado en la interfaz web está expuesto para automatización API determinista.

DominioEndpoints ClaveCapacidades
Usuarios y Ciclo MasivoGET/POST /users, GET /users/generate, POST /users/bulk-create, POST /users/bulk-extendCrear cuentas, aprovisionar flotas por lotes y extender cuotas o TTLs masivamente
Control por UsuarioGET /users/:id/config, POST /users/:id/extend|revoke|restore|reset-traffic|rotate-token|kick, PUT /users/:id/group|expiration|restrictions, GET /users/:id/sessionsObtener configs de cliente, rotar tokens, expulsar sesiones activas y ajustar límites por usuario
Planes y ShaperGET/POST /plans, DELETE /plans/:id, POST /shaper/applyGestionar plantillas de tarifas y aplicar reglas de ancho de banda/shaper en vivo
Cascada y UpstreamsPUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-trafficCambiar modos de enrutamiento en cascada, sondear nodos de salida, alternar upstreams y reiniciar contadores
Monitoreo y AuditoríaGET /overview, GET /health, GET /metrics, GET /sessions, POST /sessions/:id/kick, GET/DELETE /logs, POST /logs/simulate, GET /api-auditComprobaciones de salud, telemetría Prometheus, terminación de sesiones en vivo y logs de auditoría API
Webhooks y ClavesGET/POST /webhooks, DELETE /webhooks/:id, GET/POST /api-keys, DELETE /api-keys/:idCiclo de vida programático para suscriptores webhook HMAC y claves API con alcance
Servicios, Seguridad y LicenciaPOST /services/toggle|restart|update-adblock|unban-ip|clear-auth-logs, PUT /settings/security-mode, GET /license/status, POST /license/activateControl de demonios, desbloqueo de IPs en Fail2ban, actualizaciones AdBlock y activación de licencia
Corporate GatewayGET /enterprise/overview, POST /enterprise/users/:id/toggle, .../enterprise/users/:id, .../enterprise/gateways/:idPlano 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ón

Arquitecturas de producción comunes construidas sobre la REST API de Apium, Claves RBAC, Webhooks y Prometheus.

EscenarioPrimitivas API UtilizadasBeneficio Operativo
Bots de Telegram y Facturación SaaSClave users:write + POST /users, /users/bulk-create, /extend, Subscriptions + WebhooksEntrega instantánea de clave tras el pago, renovaciones automatizadas, cero trabajo manual de admin
Onboarding Corporativo HR / IAMusers: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 FlotaClave monitoring:read + GET /metrics, /health, /api-audit + lista blanca IPPaneles Grafana y alertas sin exponer permisos de escritura
Automatización de Cascada y Shapersystem:write + plans:write + PUT /cascade/mode, POST /upstreams/check, POST /shaper/applyFailover dinámico entre países de salida y aplicación automatizada de ancho de banda