Skip to content

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.

Keyright CloudRegístrate en keyright.delta1labs.comNosotros alojamos el servicio de emisión$BASE = keyright.delta1labs.com$TOKEN = token de sesión de equipoAutoalojadoTú despliegas el servicio de emisiónen tu propia infraestructura$BASE = URL de tu instancia$TOKEN = KEYRIGHT_ADMIN_TOKENTu producto + SDK de Keyright — idéntico en ambos casosmismo código, formato de licencia y clave pública; solo cambian ServiceUrl + token de administración
Ambas rutas se encuentran en el mismo código de aplicación — elige un modo, define `$BASE` y `$TOKEN`, y el resto de esta guía es común.

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:

El Home del panel de Keyright: una barra lateral izquierda (Home, Licenses, Customers, Products, Releases & coverage, Usage & credits, Resellers, Developers, Activity, Settings) con una insignia Self-hosted junto al nombre del espacio de trabajo, cuatro tarjetas de resumen — Active licenses 4 de 6, Active devices 4, Expiring in 30 days 1, Revoked 1 — y una lista de verificación 'Finish setting up' cuyos elementos son Create your first product, Add an edition (seats and features), Issue a license, Add the SDK to your app, See your first device activate y Connect your store, junto a un gráfico de licencias emitidas y un feed de actividad reciente.
El Home del panel tras iniciar sesión — la lista de verificación "Finish setting up" refleja los pasos 2–4 de esta guía.

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:

La lista Products mostrando un producto, Acme App (slug acme-app): la columna Editions lista enterprise, pro y starter como insignias, la columna Licenses dice 4 / 6, la columna Trial muestra una insignia '14-day trial · pro' y la columna Signing key muestra una insignia 'Per-product key' — con un botón New product arriba a la derecha.
El paso 2 empieza en Products → New product. Cada producto lista sus ediciones, su prueba y su clave de firma de un vistazo.
# 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:

La página del producto Acme App en su pestaña Overview (pestañas: Overview, Editions, Trials, Releases, Pricing, Signing key, Messages). Una columna derecha muestra una tarjeta Trial (prueba de 14 días en la edición pro, 1 puesto), una tarjeta Signing key etiquetada 'Per-product key — Licenses for this product are signed with their own key. Embed its public key in the app.', y una tarjeta Editions que lista enterprise (25 puestos; derechos export, sso, airgap, max-projects), pro (3 puestos; export, max-projects) y starter (1 puesto; max-projects).
La página del producto: cada edición lleva su número de puestos y sus derechos (export, max-projects…), y la tarjeta de clave de firma por producto contiene la clave pública que integras en el paso 3.

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 el signingPublicKey del 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én GET $BASE/admin/account → integration.signingPublicKey).

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 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.

La pantalla Developers → Quickstart titulada 'Add the SDK to your app', con el producto Acme App seleccionado en un desplegable y pestañas de lenguaje para .NET, Node.js, Python y Java. Bajo la pestaña .NET muestra el comando de instalación 'dotnet add package Keyright.NET' y un fragmento copiable rellenado con Product = acme-app, una larga cadena PublicKeyBase64 y ServiceUrl, que llama a ActivateAsync y luego a Validate y condiciona con License.IsEnabled(\
El generador de fragmentos del paso 3 (Developers → Quickstart): elige el producto y el lenguaje y rellena por ti el slug, la clave pública y la URL del servicio.

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:

LenguajePaqueteGuía
.NETKeyright.NET (NuGet)Integración del SDK de .NET
Node.jskeyright (npm)Integración del SDK de Node.js
Pythonkeyright (PyPI)Integración del SDK de Python
Javacom.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):

La lista Licenses de acme-app con un botón Issue license arriba a la derecha y controles de búsqueda, filtro por estado, Export e Import CSV. Seis filas, cada una con el licenciatario, la clave de licencia, producto·edición, puestos usados/total, vencimiento y una etiqueta de estado: Stark Industries (pro, 2/3, perpetua, activa), Wayne Enterprises (enterprise, 0/10, perpetua, revocada), Umbrella Ltd (pro, 0/3, vencida el 1 de mar de 2026), Initech LLC (pro, 0/1, vence 'en 10 días' el 22 de oct de 2026), Globex Corporation (enterprise, 1/25, activa, vence el 1 de jun de 2027) y Acme Inc. (pro, 1/3, perpetua, activa).
Paso 4: emite desde Licenses → Issue license. Cada fila muestra puestos usados/total, vencimiento y estado — activa, revocada, vencida o a punto de vencer.
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”; StatusBadge para 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:

La página de la licencia de Stark Industries (clave LIC-58D5ECC3A42E35D84311, Acme App · pro · perpetua, contacto jarvis@stark.com) con las acciones Renew, Add seats, License file y Send portal link y las pestañas Overview, Devices, Coverage, Credits e History. Un banner 'What the customer sees' dice 'Your license covers versions released on or before Oct 12, 2027' sobre un comprobador de cobertura. La sección Devices muestra 2 de 3 puestos en uso — las máquinas WORKSTATION-STAR y DESKTOP-STARK-01, ambas en línea, cada una con un lease que se renueva antes del 26 de oct de 2026 y un botón Free seat. Un panel Details lista la edición pro, 3 puestos (2 en uso), plazo perpetuo y los derechos export y max-projects: 10, y una Danger zone ofrece Transfer ownership y Revoke.
Después de que el cliente active, su máquina aparece en la pestaña Devices (2 de 3 puestos en uso) — junto a la frase de cobertura, los derechos y las acciones de renovar/revocar.

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 Product del 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 define KeyrightCoverageVersion / KeyrightCoverageEntitlementDate desde 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

ÁreaEndpointAuthPropósito
RuntimePOST /v1/activateningunaActivar una clave en una máquina → lease firmado. Cuerpo: { key, machineId, product }
RuntimePOST /v1/validateningunaValidar/refrescar sin consumir un puesto. Cuerpo: { key, machineId, product }
AdminGET/POST /admin/products, /admin/products/{slug}/tierstoken de administraciónGestionar productos y niveles
AdminPOST /admin/products/{slug}/signing-keytoken de administraciónGenerar/rotar la clave de firma de un producto → signingPublicKey
AdminPOST /admin/licenses, /admin/licenses/{id}/{revoke,renew,transfer,deactivate,offline-lease}token de administraciónEmitir y gestionar licencias
AdminGET /admin/licenses, /admin/overview, /admin/licenses/{id}/activationstoken de administraciónInformes
AdminGET /admin/self-licensetoken de administraciónSolo autoalojado: el estado de la licencia de esta instancia (edición, fase, días restantes)
AdminGET/POST /admin/teamtoken de ownerMiembros del equipo
RuntimePOST /v1/coverageninguna (clave de licencia)¿Está cubierta la versión X para esta licencia? — el bloque de construcción de tu propia puerta de descargas
AdminPOST /admin/products/{slug}/releases, /admin/licenses/{id}/coverage/{preset,grants}, /admin/products/{slug}/coverage/{readiness,backfill,export,migrate}token de administraciónCobertura de versiones: registro, términos, relleno retroactivo, exportación para aislados
PlatformGET/POST /platform/tenants, /platform/plans, /platform/tenants/{id}/signing-keytoken de plataformaOperador multi-tenant
AuthPOST /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.