Empezar aquí
Primeros pasos
La ruta de proveedor de extremo a extremo tanto para Keyright Cloud como para autoalojado — consigue un servicio de emisión, crea un producto y una clave de firma, pon el SDK en tu aplicación, emite una licencia, verifícala en la aplicación y sal a producción.
Esta es la ruta de extremo a extremo para un proveedor que añade licenciamiento a una aplicación: consigue un servicio de emisión, crea un producto y una clave de firma, integra el SDK en tu producto, emite una licencia, verifícala en la aplicación y sal a producción. Funciona igual sea cual sea el lenguaje en el que distribuyas — el paso 3 enlaza al SDK del tuyo (o a la ruta de HTTP en bruto).
Keyright viene en dos modos de despliegue, y cada paso de abajo muestra ambos. A lo largo de toda la guía, $BASE es la URL de tu servicio de emisión y $TOKEN es tu credencial de administración, enviada en la cabecera X-Admin-Token.
Elige tu ruta
Keyright Cloud — nosotros alojamos el servicio de emisión; tú te registras y empiezas a emitir claves. Autoalojado — tú despliegas el servicio en tu propia infraestructura. La parte que construyes es la misma en ambos casos: el código del SDK, el formato firmado de licencia y la clave pública que distribuyes son idénticos. Solo difieren la URL del servicio a la que apunta tu aplicación y la credencial de administración con la que gestionas.
1. Consigue tu servicio de emisión
Cloud: crea un espacio de trabajo en keyright.delta1labs.com e inicia sesión. Tu espacio de trabajo se aprovisiona automáticamente con una clave de firma, así que puedes ir directamente al paso 2. Define $BASE=https://keyright.delta1labs.com; tu $TOKEN es un token de sesión de equipo — acuñado al iniciar sesión, y puedes invitar a compañeros (con sus propios tokens) en Settings → Team.
Autoalojado: descarga la imagen de contenedor pública, apúntala a una base de datos PostgreSQL vacía, dale los secretos que necesita (un token de administración, un secreto de cifrado de claves) y tu clave de licencia de Keyright, y arráncala — construye su propio esquema en el primer arranque y responde en /health cuando está lista. Define $BASE con la URL de tu instancia (en local es http://localhost:8080) y $TOKEN con el KEYRIGHT_ADMIN_TOKEN que generaste. El recorrido completo es la Guía de despliegue, y tu instancia necesita una clave válida para ejecutarse — consulta Licenciamiento y ediciones.
Todo a partir de aquí es igual en ambos modos; solo cambian $BASE y $TOKEN.
Una vez que has iniciado sesión aterrizas en el Home del panel, que sigue tu progreso exactamente por los pasos de abajo:
2. Crea un producto (y una edición), y luego obtén una clave de firma
Crea primero el producto — no puedes generar una clave de firma ni emitir una licencia para un producto que no existe. Desde el panel (Products → New product (Productos → Nuevo producto), luego Editions → Add edition (Ediciones → Añadir edición) — el panel llama ediciones a los niveles; la API sigue diciendo tiers), 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/edition (seat count + an entitlements template your app reads at runtime)
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","max-projects":"10"}}'
Los valores de los derechos son cadenas en el protocolo ("true"/"false" para indicadores, un entero o "unlimited" para límites). Las cuotas (licencias activas, número de productos) siguen el plan del tenant en Cloud; las ediciones de pago autoalojadas son ilimitadas. Si vendes actualizaciones (un año de actualizaciones, una versión mayor, una suscripción…), da a la edición una política de cobertura antes de emitir — consulta Cobertura de versiones.
La pestaña Overview del producto reúne todo esto — las ediciones con sus números de puestos y derechos, la prueba y la clave de firma que integrarás a continuación:
Obtén una clave de firma. Las licencias y los leases se firman con una clave RSA cuya mitad privada permanece en el servidor; tu aplicación integra solo la clave pública. Una clave es o bien por producto o bien de todo el tenant (compartida por todos tus productos).
- Por producto (recomendado):
curl -X POST $BASE/admin/products/acme-app/signing-key -H "X-Admin-Token: $TOKEN"— la respuesta incluye elsigningPublicKeydel producto. En el panel está en la pestaña Signing key del producto. - De todo el tenant: léela desde Developers → Keys, o
GET $BASE/admin/public-key(tambiénGET $BASE/admin/account→integration.signingPublicKey).
GET /admin/public-keyyGET /admin/accountdevuelven la clave del tenant, que esnullhasta que existe una clave de tenant. En una instancia autoalojada recién creada sin clave de tenant definida, genera una clave por producto (arriba) en lugar de integrar un valor nulo. Un espacio de trabajo de Cloud ya tiene una clave de tenant.
Copia la clave pública en base64 de la clave que firme las licencias de ese producto — la pegarás en el SDK en el paso 3. El panel se abre en una vista Básico tranquila que cubre exactamente estos pasos; cambia a la vista Intermedio o Avanzado cuando necesites todo lo demás.
3. Pon el SDK en tu producto
Este es el corazón de la integración: integra el SDK, inicialízalo con el slug de tu producto y la clave pública, y condiciona una función. El código es idéntico en Cloud y en autoalojado — lo único que cambia entre modos es ServiceUrl (tu $BASE) y, del lado del servidor, qué token de administración emitió la clave. El formato de licencia y la clave pública integrada no cambian.
El panel escribe la primera versión de este código por ti: Developers → Quickstart elige tu producto y lenguaje y rellena el fragmento con el slug del producto, su clave pública y la URL de esta instancia — cópialo directamente.
Aquí está esa integración mínima — instalar, inicializar con el slug del producto + la clave pública + la URL del servicio, activar en línea y luego condicionar una función — en cada lenguaje soportado. Pon como URL del servicio tu $BASE (la URL alojada en Cloud, la URL de tu instancia en autoalojado); todo lo demás — las llamadas al SDK, el formato firmado de licencia/lease, la clave pública integrada — es idéntico en Cloud y en autoalojado.
.NET — Keyright.NET en NuGet (multi-target netstandard2.0 y net8.0, así que funciona en .NET Framework 4.8 y .NET 6–10):
dotnet add package Keyright.NET
using Keyright.Client;
static readonly KeyrightClient License = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-app", // the product slug from step 2
PublicKeyBase64 = "MIIBIjANBgkq...", // the public key from step 2 — not a secret; it only verifies
ServiceUrl = "https://keyright.delta1labs.com", // Cloud: the hosted URL. Self-hosted: your instance URL. Omit for offline-only.
});
// When the customer enters a key, activate online: binds this machine, consumes a seat, caches a signed lease.
LicenseInfo info = await License.ActivateAsync(customerEnteredKey, ct);
// Every later launch verifies offline against the cached lease — no network round-trip.
LicenseInfo offline = License.Validate();
// Gate a paid feature on an entitlement (not on the edition), so tier changes need no new code.
if (info.IsPaid && License.IsEnabled("export"))
ShowExportCommand();
Node.js — keyright en npm (CommonJS, sin dependencias):
npm install keyright
const { KeyrightClient } = require('keyright');
const license = KeyrightClient.initialize({
product: 'acme-app', // the product slug from step 2
publicKeyBase64: 'MIIBIjANBgkq...', // the public key from step 2 — not a secret
serviceUrl: 'https://keyright.delta1labs.com', // Cloud: the hosted URL. Self-hosted: your instance URL.
});
// When the customer enters a key, activate online (binds the machine, consumes a seat, caches a signed lease).
const info = await license.activate(customerEnteredKey);
// Later launches verify offline against the cached lease — synchronous, never throws.
const { info: offline } = license.validate();
// Gate a paid feature on an entitlement.
if (info.isPaid && info.entitlements.isEnabled('export')) {
showExportCommand();
}
Python — keyright en PyPI (Python 3.8+):
pip install "keyright>=1.1.4"
from keyright import KeyrightClient, KeyrightOptions
license = KeyrightClient.initialize(KeyrightOptions(
product="acme-app", # the product slug from step 2
public_key_base64="MIIBIjANBgkq...", # the public key from step 2 — not a secret
service_url="https://keyright.delta1labs.com", # Cloud: the hosted URL. Self-hosted: your instance URL.
))
# When the customer enters a key, activate online (synchronous).
info = license.activate(customer_entered_key)
# Later launches verify offline against the cached lease; validate() returns (info, source).
offline, source = license.validate()
# Gate a paid feature on an entitlement.
if info.is_paid and info.entitlements.is_enabled("export"):
show_export_command()
Java — com.delta1labs:keyright en Maven Central (Java 17+, sin dependencias en tiempo de ejecución):
<dependency>
<groupId>com.delta1labs</groupId>
<artifactId>keyright</artifactId>
<version>1.1.4</version>
</dependency>
import com.delta1labs.keyright.KeyrightClient;
import com.delta1labs.keyright.KeyrightOptions;
import com.delta1labs.keyright.LicenseInfo;
KeyrightClient client = KeyrightClient.initialize(
new KeyrightOptions()
.product("acme-app") // the product slug from step 2
.publicKeyBase64("MIIBIjANBgkq...") // the public key from step 2 — not a secret
.serviceUrl("https://keyright.delta1labs.com")); // Cloud: the hosted URL. Self-hosted: your instance URL.
// When the customer enters a key, activate online (synchronous).
LicenseInfo info = client.activate(customerEnteredKey);
// Later launches verify offline against the cached lease.
LicenseInfo offline = client.validateInfo();
// Gate a paid feature on an entitlement.
if (info.isPaid() && info.entitlements.isEnabled("export")) {
showExportCommand();
}
Cualquier lenguaje (HTTP en bruto, sin SDK) — la API de runtime es JSON simple sobre HTTP, así que Go, Rust, C++, PHP, Ruby… hablan con ella directamente. Activa una máquina y luego verifica tú mismo el lease firmado:
curl -s -X POST "$BASE/v1/activate" -H "content-type: application/json" \
-d '{"key":"LIC-9F3A...","machineId":"<your stable per-machine id>","product":"acme-app"}'
# -> { "status":"ok", "seats":3, "used":1, "lease":"{...signed lease JSON...}" }
Guarda la cadena lease tal cual y verifica su firma RSA contra tu clave pública integrada — reconstruye el payload canónico krlease1|… y compruébalo con PKCS#1 v1.5 / SHA-256 — antes de confiar en él. Una vez que verifica, lee tier para la edición y entitlements para las condiciones por función, y vuelve a validar periódicamente (POST /v1/validate) para recoger revocaciones. Falla de forma cerrada ante cualquier estado distinto de ok o un lease que no verifique. La receta completa a nivel de bytes (con un ejemplo en Go que puedes portar) está en Usa la API HTTP directamente.
Cada SDK verifica la firma contra tu clave pública integrada, comprueba la vinculación a la máquina y el vencimiento, guarda el lease en caché localmente y reactiva automáticamente antes de que expire. Todos fallan de forma cerrada al estado gratuito/sin licencia si la verificación falla o la clave se revoca — y como los cinco clientes verifican el mismo formato firmado, una línea de productos en varios lenguajes comparte un tenant y una clave pública.
Para el recorrido completo por lenguaje — desactivación, leases offline/aislados, pruebas, bloqueo por equipo, rotación de claves y cobertura de versiones — sigue la guía completa del tuyo:
| 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 |
¿Qué cambia entre Cloud y autoalojado? Solo la URL base y el token de administración. Pon ServiceUrl con la URL alojada para Cloud o con la URL de tu instancia para autoalojado; todo lo demás — las llamadas al SDK, el formato de licencia y lease, integrar la clave pública — es igual. Consulta Condicionar funciones para derechos y límites en profundidad.
4. Emite una licencia y verifícala en la aplicación
Emite una licencia de pago desde Licenses → Issue license en el panel, o mediante la API (omite id para autogenerar la clave; inclúyelo para importar una existente):
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.
El cliente pega esa clave en tu aplicación, que llama a ActivateAsync (en línea) — vincula la máquina, consume un puesto y guarda en caché un lease firmado para que las llamadas posteriores a Validate() tengan éxito offline. La vinculación a la máquina es automática: Activate recibe solo la clave; el SDK deriva un id de máquina estable del host, de modo que una clave de un solo puesto no puede ejecutarse en dos máquinas (el cuerpo en bruto de POST /v1/activate lleva { key, machineId, product } — el SDK rellena machineId por ti). Lo que lees de vuelta en LicenseInfo:
IsPaid/IsTrial— si es una licencia de pago o de prueba (ambas se activan por la misma ruta).IsEnabled("flag")/GetLimit("name", fallback)— comprobaciones de derechos que fallan de forma cerrada.DaysRemaining/ExpiryUtc— para una insignia “quedan 27 días”;StatusBadgepara una etiqueta como “Pro Trial”.
A medida que cada máquina se activa, aparece en la pestaña Devices de esa licencia, consumiendo un puesto — puedes ver qué dispositivos están vinculados, liberar un puesto y leer los derechos que lleva la licencia:
Las rutas completas de activación y offline están en Activación y puestos y Offline y aislado.
Obtener una clave de prueba. Si habilitaste una prueba de autoservicio en el producto (Products → Trials), tu aplicación obtiene una clave de prueba llamando directamente al endpoint público de pruebas — no hay 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 correo la clave de prueba a la dirección (no hay clave en la respuesta — requiere SMTP configurado en la instancia); el cliente introduce luego esa clave y se la pasa a ActivateAsync() como cualquier otra clave. Se activa y valida exactamente igual que una clave de pago; info.IsTrial es true y DaysRemaining cuenta hacia atrás. Flujo completo: Pruebas de autoservicio.
5. Sal a producción
Ambos modos
- La clave pública integrada en la compilación que distribuyes coincide con la clave que firma las licencias de ese producto.
- El slug
Productdel SDK coincide con el producto para el que emites licencias (el servidor delimita la activación por producto). - Decide offline u online (o ambos): un archivo offline para aislado/empresa, activación en línea para la aplicación de puestos y la revocación — consulta Offline y aislado.
- Puestos y vencimiento correctamente definidos en la edición/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 al estado gratuito en el siguiente refresco del lease. Consulta Revocar, renovar y vencimiento. - Si aplicas cobertura de versiones, rellena retroactivamente cada licencia emitida antes de la cobertura (Releases & coverage → Enforcement readiness) antes de distribuir una compilación con
KeyrightRequireCoverage, y defineKeyrightCoverageVersion/KeyrightCoverageEntitlementDatedesde tu pipeline de release — Cobertura de versiones.
Solo Cloud
- Si vendes mediante una tienda / Merchant-of-Record, conecta el cumplimiento a
POST /webhooks/fulfill/{slug}para que los pedidos pagados emitan claves automáticamente — Cumplimiento desde la tienda. - Confirma que tu plan cubre los números de licencias activas y productos que esperas (mejora en Settings → Plan & billing).
Solo autoalojado
- Ten un plan de copia de seguridad para la base de datos y para tu secreto de cifrado de claves — perder ese secreto significa perder todas las claves de firma. Haz también copia de la licencia de tu propia instancia.
- Ten preparado un plan de rotación de claves de firma.
- Mantén instalada una licencia de instancia válida — una instancia autoalojada falla de forma cerrada y deja de atender llamadas de runtime una vez que su propia licencia caduca más allá de la gracia (Licenciamiento y ediciones).
La API de un vistazo
| Área | Endpoint | Auth | Propósito |
|---|---|---|---|
| Runtime | POST /v1/activate | ninguna | Activar una clave en una máquina → lease firmado. Cuerpo: { key, machineId, product } |
| Runtime | POST /v1/validate | ninguna | Validar/refrescar sin consumir un puesto. Cuerpo: { key, machineId, product } |
| Admin | GET/POST /admin/products, /admin/products/{slug}/tiers | token de administración | Gestionar productos y niveles |
| Admin | POST /admin/products/{slug}/signing-key | token de administración | Generar/rotar la clave de firma de un producto → signingPublicKey |
| Admin | POST /admin/licenses, /admin/licenses/{id}/{revoke,renew,transfer,deactivate,offline-lease} | token de administración | Emitir y gestionar licencias |
| Admin | GET /admin/licenses, /admin/overview, /admin/licenses/{id}/activations | token de administración | Informes |
| Admin | GET /admin/self-license | token de administración | Solo autoalojado: el estado de la licencia de esta instancia (edición, fase, días restantes) |
| Admin | GET/POST /admin/team | token de owner | Miembros del equipo |
| Runtime | POST /v1/coverage | ninguna (clave de licencia) | ¿Está cubierta la versión X para esta licencia? — el bloque de construcción de tu propia puerta de descargas |
| Admin | POST /admin/products/{slug}/releases, /admin/licenses/{id}/coverage/{preset,grants}, /admin/products/{slug}/coverage/{readiness,backfill,export,migrate} | token de administración | Cobertura de versiones: registro, términos, relleno retroactivo, exportación para aislados |
| Platform | GET/POST /platform/tenants, /platform/plans, /platform/tenants/{id}/signing-key | token de plataforma | Operador multi-tenant |
| Auth | POST /auth/login → /auth/mfa, /auth/session, /auth/sso | — | Inicio de sesión del panel → token de sesión |
Los cuerpos de runtime usan machineId (una huella estable por máquina) y product (el slug del producto) junto a la key de licencia — los nombres de campo no reconocidos se tratan como una clave desconocida. Los detalles completos de solicitud/respuesta por lenguaje están en las guías del SDK y de la API HTTP; los endpoints de cobertura están documentados en Cobertura de versiones.
El mapa completo de endpoints está en la referencia de la API HTTP.