Skip to content

Casos de uso

Activar, desactivar y mover puestos

Vincula una clave a una máquina, libera ese puesto para que el cliente pueda pasar a una nueva, y hazlo para licencias de prueba, anuales y perpetuas — en línea, offline/aisladas, o del lado del proveedor cuando una máquina ya no existe — con exactamente lo que ve tu aplicación en cada caso.

Objetivo

Convierte una clave de licencia en una instalación licenciada y en funcionamiento en una máquina concreta — y deja que el cliente (o tú) libere ese puesto más adelante para que pueda pasar a otra máquina sin comprar otro puesto. Este es el ciclo de vida cotidiano de la activación: activar vincula una clave a una máquina y consume un puesto; desactivar lo libera; la misma clave funciona en licencias de prueba, anuales (por plazo) y perpetuas.

El código de abajo es C# (Keyright.NET), pero la forma del SDK es idéntica en los paquetes de Node, Python y Java — consulta el repositorio de samples ejecutable.

Cuándo usarlo

  • Úsalo para el flujo normal: un cliente introduce su clave y tu aplicación la activa; más tarde retira un portátil y quiere recuperar ese puesto.
  • Usa la ruta del lado del proveedor cuando una máquina está muerta, reinstalada o inaccesible y el cliente no puede liberar el puesto por sí mismo.
  • Usa la ruta offline para una máquina que no puede llegar al servicio en absoluto — tú acuñas un lease firmado vinculado a esa única máquina.
  • No recurras a esto para cambiar qué otorga una licencia — el vencimiento, los puestos y las renovaciones se tratan en renovación/vencimiento, y qué versiones del producto cubre está en Vender mejoras y controlar versiones.

Las tres formas de licencia

Una licencia lleva un nivel, un número de puestos, un vencimiento opcional y un indicador de prueba opcional. Esos se combinan en las tres formas que ven tus clientes:

FormaExpiryUtcIsTrialQué muestra tu aplicación
Perpetuanullfalse“Licensed — perpetual”
Anual / por plazouna fechafalse“Licensed — expires 31 Dec 2027”
Prueba / evaluaciónuna fechatrue“Evaluation — expires 31 Dec 2027 (N days left)”

En tu código

Tu aplicación lee todo esto del LicenseInfo que devuelve Activate/Validate — nunca analizas una cadena de clave tú mismo:

var info = await client.ActivateAsync(licenseKey);
if (info.Status != LicenseStatus.Valid)      // fail closed
    return ShowUnlicensed(info.Message);

string banner = info.IsTrial
    ? $"Evaluation — expires {info.ExpiryUtc:d} ({info.DaysRemaining} days left)"
    : info.ExpiryUtc is null
        ? "Licensed — perpetual"
        : $"Licensed — expires {info.ExpiryUtc:d}";

Activar (en línea)

ActivateAsync(key) envía la huella digital de la máquina y la clave al servicio de emisión. El servicio comprueba el número de puestos, vincula la licencia a esta máquina y devuelve un lease firmado que el SDK almacena en caché localmente. A partir de ahí Validate() funciona offline contra ese lease en caché (consulta Seguridad y el modelo de leases).

Reactivar la misma máquina es idempotente — refresca el lease y nunca consume un segundo puesto. Llamar a ActivateAsync en cada arranque (cuando hay conexión) es el patrón recomendado: mantiene el lease fresco de forma silenciosa.

La llamada tiene la misma forma en todos los SDK, y sobre HTTP puro es un único POST a /v1/activate que devuelve el lease firmado que hay que guardar en caché:

.NET

LicenseInfo info = await License.ActivateAsync(customerEnteredKey, ct);
if (info.IsValid && info.IsPaid) ShowLicensedUi(info.StatusBadge);   // lease cached; runs offline until it expires
else ShowActivationError(info.Message);                              // stays Free, e.g. "All seats … are in use."

Node.js

const info = await license.activate(customerEnteredKey);
if (info.isValid && info.isPaid) showLicensedUi(info.statusBadge);
else showActivationError(info.message);

Python

info = license.activate(customer_entered_key)
if info.is_valid and info.is_paid:
    show_licensed_ui(info.status_badge)
else:
    show_activation_error(info.message)

Java

LicenseInfo info = client.activate(customerEnteredKey);
if (info.isValid() && info.isPaid()) showLicensedUi(info.statusBadge());
else showActivationError(info.message());

Cualquier lenguaje (HTTP puro)

curl -s -X POST "$BASE/v1/activate" -H "content-type: application/json" \
  -d '{"key":"LIC-…","machineId":"<stable-machine-id>","product":"acme-app"}'
# status:"ok" returns a signed "lease" string — store it verbatim and verify it offline yourself.
# Fail closed on any other status, a non-2xx code, or a lease that doesn't verify.

Activación de prueba. Una clave de prueba se activa exactamente como una clave de pago — misma llamada, mismo modelo de puestos — simplemente vuelve con IsTrial == true y un vencimiento:

var info = await client.ActivateAsync(trialKey);
// info.IsTrial == true, info.ExpiryUtc == the trial end, info.DaysRemaining counts down

Muestra el banner de evaluación y condiciona lo que quieras detrás de info.IsTrial. Cuando pasa la fecha de la prueba, la activación/validación devuelve LicenseStatus.Expired y vuelves a tu estado sin licencia. Las pruebas tienen en cuenta la duración desde la primera activación y la manipulación del reloj — un cliente no puede recuperar tiempo retrasando el reloj (consulta la página de seguridad). Las pruebas normalmente se obtienen por autoservicio desde tu propio sitio; consulta Ofrecer una prueba gratuita.

Activación perpetua. Una licencia perpetua no tiene vencimiento. Actívala una vez; ExpiryUtc es null, así que se ejecuta tu rama “perpetua”. El lease sigue teniendo un TTL corto y se refresca en la siguiente activación en línea — la licencia nunca vence, pero el lease offline sigue siendo un token de gracia de corta duración (eso es lo que impide que una licencia perpetua se copie a máquinas ilimitadas offline).

Activación anual / por plazo. Llamada idéntica; ExpiryUtc es la fecha hasta la que está pagada. Usa info.IsExpiringSoon() / info.DaysRemaining para avisar a los clientes antes de la renovación. Pasada la fecha, la activación devuelve Expired. Renovar es un cambio del lado del proveedor sobre la licencia (POST /admin/licenses/{id}/renew) — el cliente conserva la misma clave y simplemente vuelve a activar para recoger el nuevo vencimiento.

Cuando no quedan puestos. Si una máquina nueva intenta activar una licencia cuyos puestos están todos en uso, el servicio devuelve LicenseStatus.SeatLimit — muestra un mensaje claro de “todos los puestos en uso — libera uno primero”. (De nuevo, la misma máquina reactivándose nunca se topa con esto.)

La lista Licenses de Keyright para Acme App; cada fila muestra el licenciatario, la edición, una columna SEATS con recuentos usados/total (Stark Industries 2/3, Wayne Enterprises 0/10, Globex Corporation 1/25, Acme Inc. 1/3), un vencimiento y una píldora de estado — active, revoked, expired, y un aviso de vencimiento próximo 'in 10 days' en Initech LLC.
La lista Licenses muestra puestos usados / total por licencia, de modo que ves de un vistazo qué claves tienen un puesto libre antes de que active una máquina nueva.

Mover una máquina (desactivación iniciada por el cliente)

Desactivar libera el puesto de esta máquina y borra el lease local, de modo que el puesto queda inmediatamente disponible en otro lugar. Así es como un cliente cambia de máquina: desactiva en la máquina antigua y luego activa en la nueva, que toma el puesto liberado. Todos los SDK exponen la misma llamada, y sobre HTTP puro es POST /v1/free-seat:

.NET

await License.DeactivateAsync(key);   // frees this machine's seat and clears the cached lease

Node.js

const status = await license.deactivate(key);   // 'ok' | 'not_found'; throws if the service is unreachable

Python

status = license.deactivate(key)   # "ok" | "not_found"; raises if the service is unreachable

Java

String status = client.deactivate(key);   // "ok" | "not_found"; throws IllegalStateException if unreachable

Cualquier lenguaje (HTTP puro)

curl -s -X POST "$BASE/v1/free-seat" -H "content-type: application/json" \
  -d '{"key":"LIC-…","machineId":"<stable-machine-id>","product":"acme-app"}'
# -> {"status":"ok"} — delete your cached lease at the same time

La desactivación no tiene alternativa offline en ningún SDK — liberar un puesto es un cambio del lado del servidor, así que la llamada falla (lanza una excepción) si no se puede llegar al servicio. Funciona igual para licencias perpetuas, anuales y de prueba. Tras la desactivación, Validate() devuelve NoLicense en esa máquina.

Lo que haces tú (lado del proveedor)

Liberar un puesto por el cliente (desactivación forzada)

Cuando una máquina muere, se reinstala o un cliente no puede acceder a ella, tú liberas el puesto desde tu backend — sin necesidad de cliente.

Panel: abre la licencia en la vista Licenses (licencias), mira sus máquinas activas y libera la que ya no existe.

La página de la licencia de Stark Industries en Keyright: un panel Devices que muestra 2 de 3 puestos en uso con los ids de máquina WORKSTATION-STAR y DESKTOP-STARK-01, cada uno marcado como online con una fecha 'lease renews by' y un botón Free seat; una tarjeta Details que lista la edición pro, 3 puestos (2 en uso), plazo perpetuo y derechos; y las acciones Renew, Add seats, License file y Send portal link encima de las pestañas.
El panel Devices de una licencia: cada máquina vinculada muestra un botón Free seat (liberar puesto), de modo que puedes devolver un puesto cuando una máquina está muerta o reinstalada — y License file acuña un lease offline para un puesto aislado.

API:

curl -X POST "https://keyright.delta1labs.com/admin/licenses/<KEY>/free-seat" \
     -H "X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"machineId":"KRM1:..."}'

POST /admin/licenses/{id}/free-seat es Support+; POST /admin/licenses/{id}/deactivate (Admin+) hace lo mismo. El siguiente Validate() en línea de la máquina ve que el puesto ha desaparecido. Puedes listar las máquinas de una licencia con GET /admin/licenses/{id}/activations.

Activación offline / aislada

Para una máquina que no puede llegar al servicio en absoluto, el proveedor emite un lease firmado de larga duración vinculado a esa única máquina. Funciona de forma idéntica para licencias de prueba y de pago.

  1. En la máquina offline, lee su ID:

    var machineId = MachineFingerprint.Current().ToBoundString();  // KRM1:...

    (o ejecuta keyright machine-id). Envía esa cadena al proveedor.

  2. El proveedor (con conectividad + un token de administración) acuña un lease para esa máquina — TTL por defecto de 365 días:

    curl -X POST "https://keyright.delta1labs.com/admin/licenses/<KEY>/offline-lease" \
         -H "X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{"machineId":"KRM1:...","days":365}'   > offline-lease.json

    Esto confirma un puesto para esa máquina (de modo que las activaciones offline siguen contando contra el límite de puestos — no puedes acuñar leases offline ilimitados más allá del número de puestos).

  3. De vuelta en la máquina offline, impórtalo — sin red de por medio:

    client.ImportOfflineLease(File.ReadAllText("offline-lease.json"));
    var info = client.Validate();   // Valid, fully offline

Como el lease está vinculado a la huella digital de esa máquina, el archivo es inútil en cualquier otra (devuelve MachineMismatch). Consulta la página de seguridad para ver por qué esto se cumple incluso offline, y Ejecutar offline / aislado para la historia offline completa.

Totalmente offline, sin ningún servicio

Si no quieres que la máquina (ni el proveedor) toque nunca una red, firma un archivo de licencia offline independiente con la CLI y distribúyelo con el producto:

keyright license --sign --licensee "Acme Corp" --product yourapp --tier pro \
  --private-key yourapp.private.json --expiry 2027-12-31 --out license.json

El cliente lo valida de forma puramente offline mediante Validate() (se descubre por ruta, por la variable de entorno KEYRIGHT_LICENSE o por la ubicación predeterminada de datos de la aplicación). En este modo no hay seguimiento de puestos — es la opción adecuada para despliegues realmente aislados o embebidos.

Una nota sobre la desactivación offline

Hoy no existe una “prueba de desactivación” generada por el cliente, así que una máquina aislada no puede devolver su puesto por sí sola. Libéralo del lado del proveedor (desactivación forzada, arriba) en cuanto tu backend tenga conectividad, o emite leases offline con un TTL lo bastante corto para que el puesto de una máquina dada de baja vuelva por sí solo cuando caduque el lease. Consulta el repositorio de samples.

Cloud vs autoalojado

El flujo de activación es idéntico en ambos modos. Solo cambian los endpoints:

  • Las llamadas en tiempo de ejecución (/v1/activate, /v1/validate, /v1/free-seat) apuntan a tu ServiceUrl — https://keyright.delta1labs.com en Keyright Cloud, la URL de tu propio servicio de emisión cuando es autoalojado.
  • Las llamadas del lado del proveedor (/admin/licenses/...) usan el mismo $BASE y un token de administración. En Keyright Cloud el token proviene de tu inicio de sesión en el panel; en autoalojado es el token de administración de tu tenant/entorno.
  • La vinculación de puestos, los leases y las rutas offline se comportan igual en ambos casos.

Verificar

  1. Activa una clave en la máquina A y confirma LicenseInfo.Status == Valid y el banner correcto (prueba / por plazo / perpetua). La lista Licenses → activations del panel muestra la máquina A.
  2. Activa la misma clave de nuevo en la máquina A — confirma que no se consume un segundo puesto (el número de puestos no cambia).
  3. Desde una máquina nueva B con los puestos llenos, confirma que obtienes LicenseStatus.SeatLimit.
  4. DeactivateAsync en A (o libera el puesto del lado del proveedor) y luego activa en B — B toma ahora el puesto liberado y el panel refleja el cambio.

Véase también