Referencia de la API HTTP

Un mapa legible de la API HTTP del servicio emisor, agrupado por área. Esta página sirve para encontrar el endpoint correcto y saber cómo se autentica; la especificación OpenAPI legible por máquina se incluye con el servicio para los esquemas completos de petición/respuesta, tipos de campos y ejemplos.

$BASE es la URL de tu servicio emisor (p. ej. https://keyright.delta1labs.com).

La autenticación de un vistazo

Cada endpoint que no es de runtime está protegido por una de estas. Toda la autenticación de admin/platform usa la cabecera X-Admin-Token (un token de sesión del inicio de sesión del panel se presenta de la misma forma).

Auth	Cabecera(s)	Quién
none	—	llamadas de runtime del cliente final (activación, validación, prueba)
tenant token	X-Admin-Token: <team/session/env-admin token>	un proveedor gestionando su propio tenant
platform token	X-Admin-Token: <KEYRIGHT_PLATFORM_TOKEN> (+ X-Tenant para /admin/*)	el operador de la plataforma
session	X-Admin-Token: <session token from /auth/*>	un usuario del panel con sesión iniciada
HMAC	X-Keyright-Signature	webhooks del proveedor de pagos
cron secret	X-Cron-Secret	el programador de notificaciones externo

Los roles tras un tenant token están restringidos por capacidad (owner ⊃ admin ⊃ support/billing ⊃ viewer); el rol mínimo de un endpoint se indica abajo donde importa. Consulta Panel de administración para el modelo de roles.

Runtime (/v1/*) — sin auth, llamado por tu aplicación / cliente

Método	Ruta	Propósito
POST	/v1/activate	Activa una clave en una máquina → consume un puesto, devuelve un lease firmado. Cuerpo: { key, machineId, product }.
POST	/v1/validate	Revalida / refresca una clave+máquina sin consumir un puesto nuevo. Cuerpo: { key, machineId, product }.
POST	/v1/free-seat	Libera el puesto que esta máquina tiene en una clave. Cuerpo: { key, machineId, product }.
POST	/v1/trial	Prueba de autoservicio: acuña una clave de prueba para un producto y la envía por email (idempotente por email — una nueva solicitud reenvía la clave existente). Cuerpo { product, email, company }. La respuesta JSON confirma { ok, trial, emailed, expiresUtc, days, created } y no contiene la clave. CORS abierto. Consulta Pruebas gratuitas de autoservicio.

Admin (/admin/*) — tenant token

Gestiona los productos, licencias y equipo de un tenant. Con el platform token requieren una cabecera X-Tenant que nombre al tenant destino.

Productos y niveles

Método	Ruta	Propósito
GET	/admin/products	Lista los productos (con niveles, recuentos de licencias, ajustes de prueba).
POST	/admin/products	Crea/actualiza un producto (nombre, slug, trialDays/trialTier/trialSeats opcionales).
POST	/admin/products/{slug}/trial	Habilita/deshabilita la prueba de autoservicio de un producto. Cuerpo { days, tier, seats } (days <= 0 la deshabilita); la respuesta los devuelve como { trialDays, trialTier, trialSeats }.
POST	/admin/products/{slug}/tiers	Crea/actualiza un nivel por producto (puestos + plantilla de derechos).
POST	/admin/products/{slug}/signing-key	Genera (o, con {"rotate":true}, rota) la clave de firma propia de este producto → devuelve signingPublicKey para embeber en tu aplicación.
GET	/admin/tiers	Lista las plantillas de nivel de todo el tenant.
POST	/admin/tiers	Crea/actualiza una plantilla de nivel de todo el tenant.

Licencias

Método	Ruta	Propósito
POST	/admin/licenses	Emite una licencia (autogenera una clave salvo que pases id).
GET	/admin/licenses[?product=]	Lista/filtra licencias.
POST	/admin/licenses/{id}/revoke	Revoca una licencia (surte efecto en la siguiente comprobación en línea).
POST	/admin/licenses/{id}/renew	Amplía la caducidad / cambia puestos, sin clave nueva.
POST	/admin/licenses/{id}/transfer	Transfiere la propiedad a un nuevo titular (historial auditado).
GET	/admin/licenses/{id}/transfers	La cadena de propiedad de la licencia.
POST	/admin/licenses/{id}/deactivate	Libera el puesto de una máquina concreta.
POST	/admin/licenses/{id}/offline-lease	Firma un lease sin conexión para el id de una máquina aislada (air-gapped).
GET	/admin/licenses/{id}/activations	Máquinas en las que una licencia está activa (metadatos del dispositivo + geolocalización).
POST	/admin/licenses/bulk-revoke	Revoca muchas por id, resultados por elemento.
POST	/admin/licenses/bulk-seats	Cambia recuentos de puestos en bloque, resultados por elemento.
GET	/admin/revocation-list	Construye + firma una lista de revocación sin conexión distribuible.

Equipo

Método	Ruta	Auth	Propósito
GET/POST	/admin/team	owner	Lista / invita miembros del equipo (la invitación envía por email un token de un solo uso).
POST	/admin/team/{id}	owner	Habilita/deshabilita un miembro.
POST	/admin/team/{id}/set-password	owner	Aprovisiona la contraseña del panel de un miembro.

Espacio de trabajo, reportes e integración

Método	Ruta	Propósito
GET	/admin/overview	Panel de inicio: resumen de suscripción, recuentos, desglose por producto, tendencia, renovaciones próximas.
GET	/admin/account	Tenant + plan + uso + el bloque de integración (URL base, clave pública de firma, URL de webhook).
GET	/admin/stats	Totales por producto (licencias, puestos activos, que caducan pronto, revocadas).
GET	/admin/usage	Puestos asignados/usados por licencia + totales (facturación basada en uso).
GET	/admin/export[?product=]	Paquete completo de licencias + activaciones.
GET	/admin/audit	Registro de auditoría atribuible de acciones que modifican datos.
GET	/admin/public-key	La clave pública de firma del tenant. null hasta que existe una clave de tenant — para una clave por producto usa POST /admin/products/{slug}/signing-key en su lugar.
GET	/admin/self-license	Solo autoalojado: el estado de licencia de esta propia instancia — status, edition, isTrial, phase (active/expiring/grace/gated), daysUntilExpiry, graceDaysLeft.
POST	/admin/workspace	Owner: nombre del espacio de trabajo, logo, marca de onboarding.
POST	/admin/webhook-secret/rotate	Owner: rota el secreto del webhook de fulfillment de este tenant.
POST	/admin/billing/checkout	Owner: abre un checkout de Lemon Squeezy para mejorar el plan.
POST/GET	/admin/resellers, /admin/resellers/{id}	Gestiona revendedores (emisores limitados y con alcance por producto).

Platform (/platform/*) — platform token

La superficie del operador multi-tenant. Deshabilitada (503) cuando KEYRIGHT_PLATFORM_TOKEN no está definido (autoalojamiento de un solo tenant).

Método	Ruta	Propósito
POST	/platform/tenants	Crea una empresa/tenant → devuelve el token inicial del owner, la clave pública de firma, el secreto del webhook.
GET	/platform/tenants[?slug=]	Lista tenants.
POST	/platform/tenants/{id}	Habilita/deshabilita, asigna plan, estado de suscripción.
POST	/platform/tenants/{id}/signing-key	Importa (PKCS#8 de Nebula) o genera una clave de firma de tenant.
POST	/platform/tenants/{id}/rotate-signing-key	Rota la clave de firma de un tenant.
POST	/platform/tenants/{id}/rotate-webhook-secret	Rota el secreto del webhook de un tenant.
GET	/platform/plans	Catálogo completo de planes (incl. planes no públicos).
POST	/platform/plans/{key}	Crea/actualiza los precios, cuotas y características de un plan.

Auth (/auth/*) — inicio de sesión del panel → token de sesión

Estos acuñan un token de sesión que luego presentas como X-Admin-Token en los endpoints /admin/* de arriba. El inicio de sesión es por tenant (pasa X-Tenant; por defecto es default).

Método	Ruta	Propósito
POST	/auth/login	Email + contraseña → un desafío MFA.
POST	/auth/mfa	Email + contraseña + código TOTP → token de sesión.
POST	/auth/sso	Intercambia un token de ID OIDC validado por un token de sesión.
POST	/auth/session	Intercambia un token de acceso de inicio de sesión nativo / social por un token de sesión.
GET	/auth/oauth/{provider} → /auth/oauth/{provider}/callback	OAuth nativo de Google / GitHub en tu propio dominio.

Plans (/plans) — público

Método	Ruta	Auth	Propósito
GET	/plans	none	Catálogo público de precios (planes marcados como públicos), para una página de precios o un registro.

Webhooks (/webhooks/*) — HMAC

Disparadores de fulfillment: un proveedor de pagos (o un adaptador ligero) hace POST de un evento normalizado, firmado con HMAC sobre el cuerpo en bruto en X-Keyright-Signature. “Paid” acuña una licencia (idempotente por referencia de pedido); “refund”/“cancel” la revoca. El procesamiento del pago en sí queda fuera de alcance.

Método	Ruta	Propósito
POST	/webhooks/fulfill/{slug}	Webhook por tenant; el tenant se toma de la ruta y se verifica con el secreto de ese tenant.
POST	/webhooks/fulfill	Webhook heredado de todo el despliegue (un solo tenant, KEYRIGHT_WEBHOOK_SECRET).

Operacional

Método	Ruta	Auth	Propósito
GET	/health	none	Sonda de vivacidad/versión.
GET	/branding	none	Nombre/logo/color de marca white-label para cualquier interfaz.
POST	/internal/notifications/run	cron secret	Ejecuta el escaneo diario de caducidad/límite de puestos (dispáralo desde un programador externo).
varios	/portal/*	magic link	Portal de cliente de autoservicio (ver licencias, re-descargar clave/archivo, liberar puestos).

El propio panel se sirve en /dashboard — consulta Panel de administración.