LuawardDocs

Resumen de la API para desarrolladores

Autentica solicitudes, entiende los límites y administra los proyectos y las claves de licencia del workspace.

URL base

La Developer API la sirve el host perimetral (edge) de Luaward:

https://api.luaward.com/v3

Usa api.luaward.com para la API v3. Los loaders usan luaward.com y las páginas de claves key.luaward.com. Los dominios personalizados aún no están disponibles.

Los paquetes oficiales de JavaScript/TypeScript (npm @luaward/sdk), Python (PyPI luaward) y la CLI (npm @luaward/cli) ya están publicados en registros públicos. Consulta SDKs y CLI y github.com/luaward para ver los comandos de instalación y credenciales. La extensión de VS Code aún no está en el Marketplace; contacta con soporte para obtener un artefacto probado.

Crear una clave de API

Abre Dashboard → API para desarrolladores y crea una clave con nombre. La clave se muestra una sola vez. Luaward guarda solo su hash, así que cópiala en un almacén de secretos del servidor y nunca la incluyas en un script, en un bundle de navegador ni en un repositorio público.

Una clave pertenece al workspace, no a un proyecto, como la clave única de la cuenta en Luarmor: lee y cambia todos los proyectos del workspace y puede crear nuevos. Un workspace puede tener hasta 10 claves activas. Solo el propietario del workspace o un administrador puede crear, revocar o eliminar claves. Una clave revocada deja de funcionar al instante.

Al crear una clave eliges lo que puede hacer: Acceso total (todo, hoy y según crezca la API), Gestionar claves (leer, y crear, cambiar, eliminar, restablecer, banear y desbanear las claves de licencia de los jugadores) o Solo lectura. También puedes limitar una clave a algunos proyectos: entonces solo ve esos (cualquier otro proyecto responde 404 PROJECT_NOT_FOUND, como si no existiera), sus estadísticas cuentan solo esos y no puede crear proyectos nuevos. Una llamada que la clave no puede hacer responde 403 INSUFFICIENT_SCOPE. Lo que la clave puede hacer y los proyectos a los que llega se fijan al crearla; para cambiarlos, crea otra clave y revoca la anterior. Los scripts y los sistemas de claves tienen scopes propios, scripts:write y keysystem:write: Acceso total los incluye, Gestionar claves no.

Autenticación

Envía la clave de desarrollador en la cabecera Authorization:

Authorization: Bearer YOUR_DEVELOPER_API_KEY

La API también acepta una cabecera api-key. La clave nunca se acepta en la dirección (por ejemplo, como parámetro de consulta), porque las direcciones acaban en los logs.

Límites

QuéLímite
Solicitudes por clave60 por minuto. Por encima: HTTP 429 con la cabecera Retry-After.
Claves erróneas desde una dirección30 por minuto. Después la dirección espera un minuto (429).
Cuerpo de la solicitudPredeterminado: 16 KiB. Código de scripts: 4 MiB; claves en lote: 512 KiB. Un cuerpo mayor devuelve 413.
Claves de licenciaLas claves creadas por la API cuentan en el límite de claves de tu plan, junto con las creadas en el dashboard. En el límite, crear devuelve 403 con PLAN_LIMIT.
ProyectosLos proyectos creados por la API cuentan en el límite de proyectos de tu plan de la misma manera (403 con PLAN_LIMIT).

IP permitidas

El workspace puede permitir las direcciones desde las que se puede llamar a su API (Dashboard → API para desarrolladores → IP permitidas: hasta 20 direcciones completas IPv4 o IPv6, cada una con una nota recordatorio). Una sola lista vale para todas las claves y todos los proyectos del workspace. Sin ninguna en la lista, cualquier dirección puede llamar. Con alguna, solo esas pueden, sea cual sea la clave usada. No se admiten rangos como 10.0.0.0/8, y quien llama desde una dirección que no se puede leer no está en la lista. Una vez guardada, el dashboard muestra la dirección con el final oculto, así que la nota es como la reconoces. El cambio se aplica en la siguiente llamada.

Cuando se rechaza una llamada

Un error responde con success: false, una frase en error y un code que un programa puede leer.

EstadoCódigoSignificado
400INVALID_BODY, INVALID_FIELDEl cuerpo no es JSON o un campo incumple una regla. INVALID_FIELD añade una lista details con cada campo.
400CONFIRM_REQUIREDEliminar un proyecto exige su nombre exacto en confirm_name.
401UNAUTHORIZEDLa clave falta, es incorrecta o está revocada.
403SUSPENDEDLa cuenta del propietario del workspace está suspendida.
403IP_NOT_ALLOWEDLa dirección no está en la lista de IP permitidas del workspace.
403PLAN_LIMITEl workspace alcanzó su límite de claves o de proyectos.
403INSUFFICIENT_SCOPELa clave no puede hacer esto: es de solo lectura, gestiona claves pero no proyectos, o está limitada a algunos proyectos e intentó crear uno.
400BUILD_NOT_READYSolo se puede servir un build terminado.
403SCRIPT_LOCKEDLuaward apagó este script; no se puede encender aquí.
404SCRIPT_NOT_FOUND, BUILD_NOT_FOUNDNo existe ese script en este proyecto, o ese build de este script.
404KEY_SYSTEM_NOT_FOUND, STEP_NOT_FOUND, BLOCK_NOT_FOUNDNo existe ese sistema de claves, paso o bloqueo en este proyecto.
409ALREADY_BLOCKEDEsa cuenta de Discord ya está bloqueada en esta página.
429TOO_MANY_BUILDSEl workspace ya tiene varios builds esperando.
503UNAVAILABLELa API no llega al servicio que sella y compila el código.
503TEMPORARILY_UNAVAILABLENo disponible temporalmente. Espera Retry-After: 30 antes de reintentar.
404PROJECT_NOT_FOUNDNo existe ese proyecto en este workspace. Un proyecto de otro workspace, uno eliminado y un id inventado responden igual.
404NOT_FOUNDNo existe esa clave en este proyecto.
409KEY_EXISTSYa existe una clave con ese valor.
409ALREADY_LINKEDLa clave ya está vinculada a otra cuenta de Discord; envía force para reemplazarla.
413TOO_LARGEEl cuerpo supera el límite de este endpoint.
429RATE_LIMITDemasiadas solicitudes, o demasiadas claves erróneas desde una dirección.

Qué queda registrado

Los cambios hechos por la API aparecen en el historial de la clave de licencia con el actor api: seguido del nombre de la clave de API: created, extended, hwid_reset, banned, unbanned. El historial de una clave eliminada se va con ella, así que la eliminación queda en el registro de auditoría del workspace. Crear, renombrar y eliminar un proyecto también se registran allí y aparecen en el feed de actividad del dashboard. Las respuestas nunca se guardan en caché (Cache-Control: no-store).

Operaciones disponibles

La API gestiona proyectos, scripts (su código, builds e interruptor general), claves de licencia una a una o en masa y el sistema de claves, y lee estadísticas, ejecuciones recientes, el registro de auditoría y los miembros. Consulta la referencia de la API, la API de scripts, Claves en masa y exportación, Estadísticas, ejecuciones y registro y la API del sistema de claves.