Documentación de KeyForge

KeyForge es la plataforma de gestión de licencias para software: crea productos, emite claves de licencia, válida desde cualquier lenguaje y controla activaciones por dispositivo.

La API REST está organizada en dos niveles:

• API pública — valida licencias directamente desde tu aplicación, sin autenticación de sesión.
• API de gestión — crea, lista y administra productos y licencias. Requiere un token Bearer (ver Autenticación).

Quickstart

1. Crea tu cuenta en /auth?mode=signup o inicia sesión con Google/GitHub.
2. Obtén tu API key desde /api-keys en el dashboard, o en /me → API Key.
3. Crea un producto indicando tipo (Web, Desktop, Mobile, IoT, API, Game). Recibirás un product_key (kf-prod-live_...).
4. Genera una licencia desde /licenses. Obtendrás una clave única (KF-XXXX-XXXX-XXXX).
5. Valídala desde tu app con una sola llamada — ver Validar una licencia más abajo.

Autenticación

1. JWT para la API de gestión

Registra o inicia sesión en la API de auth y usa el accessToken devuelto como Authorization: Bearer <token> en cada petición:

curl -X POST http://api.keyforge.aes-studio.dev/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "companyName": "Analytical Engines",
    "email": "ada@example.com",
    "password": "sup3r-secret",
    "timezone": "Europe/Madrid"
  }'

Respuesta 200:

{
  "accessToken": "eyJhbGciOi...",
  "expiresIn": 900,
  "refreshToken": "d8f5a1..."
}

curl http://api.keyforge.aes-studio.dev/api/v1/products -H "Authorization: Bearer eyJhbGciOi..."

El access token expira pronto (expiresIn en segundos); reclámalo de nuevo con POST /api/v1/auth/refresh enviando { "refreshToken": "..." }.

2. API key (kf_live_…)

Tu cuenta tiene asociada una API key permanente (kf_live_...), visible en /api-keys. Se usa como identificador de la cuenta integrando KeyForge desde tu backend (cabecera X-API-Key). No la expongas en el cliente ni en repositorios.

Rutas de auth disponibles

Validar una licencia

El endpoint de validación es público (sin JWT) — está pensado para que lo llame tu aplicación en cada arranque o sesión:

POST http://api.keyforge.aes-studio.dev/api/v1/licenses/validate
Content-Type: application/json

{
  "licenseKey": "KF-XXXX-XXXX-XXXX",
  "productKey": "kf-prod-live_4X8K9M2N7P1Q5R3T6V8W0Y4K2N",
  "deviceId":   "tu-fingerprint-de-dispositivo"
}

Campos obligatorios:

• licenseKey — la clave emitida al cliente.
• productKey — la clave de tu producto (kf-prod-live_...).
• deviceId — identificador único del dispositivo.

Opcionales: deviceInfo (por defecto, User-Agent), ipAddress, appVersion, os.

Respuesta 200 OK (válida):

{
  "valid": true,
  "maxDevices": 500,
  "expiresAt": "2026-12-01T00:00:00Z",
  "message": "License valid."
}

Respuesta 400 Bad Request (inválida/expirada):

{
  "valid": false,
  "maxDevices": 0,
  "expiresAt": null,
  "message": "License is expired."
}

Llamada típica desde Node.js:

const res = await fetch("http://api.keyforge.aes-studio.dev/api/v1/licenses/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    licenseKey: "KF-XXXX-XXXX-XXXX",
    productKey: "kf-prod-live_4X8K9M2N7P1Q5R3T6V8W0Y4K2N",
    deviceId: getDeviceFingerprint(),
  }),
});
const { valid, message, expiresAt } = await res.json();
if (!valid) throw new Error(message);

Activar un dispositivo

Registra una activación del dispositivo en la licencia. Requiere Authorization: Bearer <token> (token de la cuenta):

POST http://api.keyforge.aes-studio.dev/api/v1/licenses/activate
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "licenseKey": "KF-XXXX-XXXX-XXXX",
  "deviceId":   "tu-fingerprint-de-dispositivo",
  "deviceInfo": "MacBook Pro · macOS 15"
}

Respuesta 200 OK:

{
  "success": true,
  "message": "License activated.",
  "maxDevices": 500,
  "currentActivations": 1,
  "expiresAt": "2026-12-01T00:00:00Z"
}

API de gestión

Requiere Authorization: Bearer <token> en todos los endpoints.

Las credenciales (Bearer) se obtienen en /auth/login o /auth/register. Los eventos de licencia (/license-events) registran validaciones, activaciones y revocaciones para el historial del dashboard.

Errores

Los errores devuelven JSON con un campo message (y código HTTP adecuado):

El validador de licencias responde 400 cuando la licencia no es válida, con valid: false en el cuerpo.

Planes y límites

El plan se aplica a toda la cuenta. El uso del mes en curso aparece en /usage y en /me → Facturación. Si superas un límite, las nuevas operaciones quedan restringidas hasta el siguiente ciclo.