Guía

Primeros pasos

La ruta de extremo a extremo para un proveedor que añade licenciamiento a cualquier aplicación: obtén una clave de firma, emite una licencia, verifícala en .NET, Node, Python, Java o por HTTP en bruto, y ponla en producción.

Esta es la ruta de extremo a extremo para un proveedor que añade licenciamiento a una aplicación: obtén una clave de firma, emite una licencia, verifícala en tu aplicación y ponla en producción. Asume un servicio emisor de Keyright en ejecución (el servicio alojado o tu propio despliegue). Los pasos del proveedor de abajo son los mismos sea cual sea el lenguaje en el que distribuyas; el paso 3 enlaza al SDK de tu lenguaje (o a la ruta de HTTP en bruto si aún no hay uno).

A lo largo de todo, $BASE es la URL de tu servicio emisor — el servicio alojado (https://keyright.delta1labs.com) o tu instancia autoalojada (localmente eso es http://localhost:<KEYRIGHT_PORT>, puerto 8080 por defecto). $TOKEN es tu credencial de administrador, enviada en la cabecera X-Admin-Token: en el servicio alojado, un token de sesión de un miembro del equipo; en una instancia autoalojada, el valor de tu KEYRIGHT_ADMIN_TOKEN.

1. Crea tu producto (y un nivel)

Crea primero el producto — no puedes generar una clave de firma (paso 2) ni emitir una licencia para un producto que todavía no existe. Desde el panel (Products → Add product, luego ábrelo y Add tier), o mediante la API:

# create the product
curl -X POST $BASE/admin/products -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"name":"Acme App","slug":"acme-app"}'

# add a tier (seat count + optional entitlements template)
curl -X POST $BASE/admin/products/acme-app/tiers -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"name":"pro","seats":3,"entitlements":{"export":"true"}}'

# OPTIONAL — enable a self-service trial on the product, so customers can self-serve a time-limited key
curl -X POST $BASE/admin/products/acme-app/trial -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"days":14,"tier":"pro","seats":1}'

# issue a paid license (omit "id" to auto-generate a key; include it to import an existing one)
curl -X POST $BASE/admin/licenses -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"licensee":"Acme Inc.","product":"acme-app","tier":"pro","seats":3,"email":"owner@acme.com"}'
# -> HTTP 201
# { "id":"LIC-XXXX...", "licensee":"Acme Inc.", "product":"acme-app", "tier":"pro",
#   "seats":3, "used":0, "expiryUtc":null, "revoked":false, "trial":false, "createdAt":"..." }
# The "id" is the key you give the customer.

seats en la licencia anula los seats del nivel (el valor del nivel es el predeterminado cuando lo omites). Las cuotas (licencias activas, número de productos) se aplican según el plan del tenant en el servicio alojado; las ediciones de pago autoalojadas son ilimitadas. El flujo completo de la prueba de autoservicio — incluido cómo la aplicación de un cliente obtiene una clave de prueba — está en Pruebas de autoservicio (y en el paso 3 de abajo).

2. Obtén una clave de firma para el producto

Las licencias y los leases se firman con una clave RSA; la clave privada permanece en el servidor (cifrada con AES-256-GCM bajo la KEK del servicio) y tu aplicación embebe solo la clave pública. Una clave es o bien de todo el tenant (compartida por todos tus productos) o bien por producto.

Autoalojado (recomendado): da al producto su propia clave con curl -X POST $BASE/admin/products/acme-app/signing-key -H "X-Admin-Token: $TOKEN", cuya respuesta incluye el signingPublicKey del producto. (Alternativa de todo el tenant: define KEYRIGHT_SIGNING_KEY y lee su mitad pública desde curl $BASE/admin/public-key -H "X-Admin-Token: $TOKEN".)
Servicio alojado, espacio de trabajo nuevo: se genera una clave de tenant por ti — obtén su clave pública desde la pestaña Integration del panel, o GET $BASE/admin/account (el campo integration.signingPublicKey).
Trae tu propia clave (p. ej. para coincidir con un producto existente como Nebula.NET): importa una clave privada PKCS#8 con POST $BASE/platform/tenants/{id}/signing-key.

GET /admin/public-key y GET /admin/account devuelven la clave del tenant, que es null hasta que existe una clave de tenant. En una instancia autoalojada recién creada sin KEYRIGHT_SIGNING_KEY definido, genera una clave por producto (arriba) en lugar de embeber un valor nulo.

Embebe la clave pública de la clave que firme las licencias de ese producto. Copia la clave pública en base64; la pegarás en las opciones del SDK en el paso 3.

3. Verifica la licencia en tu aplicación

Cada SDK verifica el mismo formato firmado de licencia y lease, de modo que una línea de productos multilenguaje comparte un tenant y una clave pública. Elige tu lenguaje para el recorrido completo:

Lenguaje	Paquete	Guía
.NET	`Keyright.NET` (NuGet)	Integración del SDK de .NET
Node.js	`keyright` (npm)	Integración del SDK de Node.js
Python	`keyright` (PyPI)	Integración del SDK de Python
Java	`com.delta1labs:keyright` (Maven)	Integración del SDK de Java
Cualquier otro (Go, Rust, C++, PHP…)	—	Usa la API HTTP directamente

La forma mínima, en .NET (consulta las guías por lenguaje para Node/Python/Java y la ruta de HTTP en bruto):

var client = KeyrightClient.Initialize(new KeyrightOptions {
    Product = "acme-app",
    PublicKeyBase64 = "<your product (or tenant) public key>",
    ServiceUrl = "https://your-keyright-instance.example", // your issuing service; self-hosted → your instance URL (optional; online only)
});

// Online activation (recommended): binds this machine, returns a verified lease.
LicenseInfo info = await client.ActivateAsync(customerKey);

// Or, if you ship an offline license file / env var, just validate what's present:
LicenseInfo info2 = client.Validate();

if (info.IsPaid && client.IsEnabled("export")) { /* unlock the feature */ }

El SDK verifica la firma contra tu clave pública embebida, comprueba el vínculo con la máquina y la caducidad, almacena el lease en caché localmente y se reactiva automáticamente antes de que el lease caduque. Falla cerrado al estado libre/sin-licencia si la verificación falla o la clave está revocada.

El vínculo con la máquina es automático: Activate toma solo la clave — el SDK deriva un id de máquina estable del propio host, de modo que una clave de un solo puesto no puede ejecutarse en dos máquinas. No pasas un machineId al SDK (el cuerpo HTTP en bruto de POST /v1/activate sí lleva { key, machineId, product } — el SDK rellena machineId por ti). Node/Python/Java son idénticos; consulta sus guías.

Obtener una clave de prueba. Si habilitaste una prueba de autoservicio (paso 1), tu aplicación obtiene una clave de prueba llamando directamente al endpoint público de prueba — no hay un envoltorio del SDK para emitir una prueba:

curl -X POST $BASE/v1/trial -H "content-type: application/json" \
  -d '{"product":"acme-app","email":"user@customer.com","company":"Customer Ltd"}'
# -> { "ok":true, "product":"acme-app", "trial":true, "emailed":true, "expiresUtc":"...", "days":14, "created":true }

El endpoint envía por email la clave de prueba a la dirección (no hay clave en la respuesta — requiere SMTP configurado en la instancia); el cliente luego introduce esa clave en tu aplicación y se la pasa a Activate()/activate() como cualquier otra clave. Luego se activa y valida exactamente como una clave de pago; info.IsTrial (.is_trial) es verdadero y DaysRemaining cuenta atrás. Flujo completo y opciones: Pruebas de autoservicio.

4. Lista de verificación para producción

La clave pública embebida en la compilación distribuida coincide con la clave de firma actual del tenant.
El slug Product en el SDK coincide con el producto para el que emites licencias (el servidor acota la activación por producto).
Decide sin conexión frente a en línea (o ambos): archivo sin conexión para aislado (air-gapped)/empresa, activación en línea para la aplicación de puestos y la revocación.
Puestos y caducidad bien configurados en el nivel/licencia; prueba a alcanzar el límite de puestos.
Prueba la ruta de revocación (POST /admin/licenses/{id}/revoke) — la aplicación debería caer a libre en el siguiente refresco del lease.
Ten un plan de respaldo para la base de datos y la KEK. Perder la KEK significa perder la clave de firma de todos los tenants.
Ten un plan de rotación de la clave de firma listo.
Si vendes a través de una tienda/Merchant-of-Record, conecta el fulfillment a POST /webhooks/fulfill/{slug} para que los pedidos pagados emitan claves automáticamente.

La API de un vistazo

Área	Endpoint	Auth	Propósito
Runtime	`POST /v1/activate`	none	Activa una clave en una máquina → lease firmado. Cuerpo: `{ key, machineId, product }`
Runtime	`POST /v1/validate`	none	Valida/refresca sin consumir un puesto. Cuerpo: `{ key, machineId, product }`
Admin	`GET/POST /admin/products`, `/admin/products/{slug}/tiers`	admin token	Gestiona productos y niveles
Admin	`POST /admin/products/{slug}/signing-key`	admin token	Genera/rota la clave de firma de un producto → `signingPublicKey`
Admin	`POST /admin/licenses`, `/admin/licenses/{id}/{revoke,renew,transfer,deactivate,offline-lease}`	admin token	Emite y gestiona licencias
Admin	`GET /admin/licenses`, `/admin/overview`, `/admin/licenses/{id}/activations`	admin token	Reportes
Admin	`GET /admin/self-license`	admin token	Solo autoalojado: el estado de licencia de esta instancia (edición, fase, días restantes)

Los cuerpos de runtime usan machineId (una huella digital estable por máquina) y product (el slug del producto) junto con la key de la licencia — los nombres de campo no reconocidos se tratan como una clave desconocida. Los detalles completos de petición/respuesta por lenguaje están en las guías del SDK y la API HTTP. | Admin | GET/POST /admin/team | owner token | Miembros del equipo | | Platform | GET/POST /platform/tenants, /platform/plans, /platform/tenants/{id}/signing-key | platform token | Operador multi-tenant | | Auth | POST /auth/login → /auth/mfa, /auth/session, /auth/sso | — | Inicio de sesión del panel → token de sesión |

El mapa completo de endpoints está en la Referencia de la API HTTP.