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/v3Usa 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_KEYLa 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 clave | 60 por minuto. Por encima: HTTP 429 con la cabecera Retry-After. |
| Claves erróneas desde una dirección | 30 por minuto. Después la dirección espera un minuto (429). |
| Cuerpo de la solicitud | Predeterminado: 16 KiB. Código de scripts: 4 MiB; claves en lote: 512 KiB. Un cuerpo mayor devuelve 413. |
| Claves de licencia | Las 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. |
| Proyectos | Los 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.
| Estado | Código | Significado |
|---|---|---|
| 400 | INVALID_BODY, INVALID_FIELD | El cuerpo no es JSON o un campo incumple una regla. INVALID_FIELD añade una lista details con cada campo. |
| 400 | CONFIRM_REQUIRED | Eliminar un proyecto exige su nombre exacto en confirm_name. |
| 401 | UNAUTHORIZED | La clave falta, es incorrecta o está revocada. |
| 403 | SUSPENDED | La cuenta del propietario del workspace está suspendida. |
| 403 | IP_NOT_ALLOWED | La dirección no está en la lista de IP permitidas del workspace. |
| 403 | PLAN_LIMIT | El workspace alcanzó su límite de claves o de proyectos. |
| 403 | INSUFFICIENT_SCOPE | La clave no puede hacer esto: es de solo lectura, gestiona claves pero no proyectos, o está limitada a algunos proyectos e intentó crear uno. |
| 400 | BUILD_NOT_READY | Solo se puede servir un build terminado. |
| 403 | SCRIPT_LOCKED | Luaward apagó este script; no se puede encender aquí. |
| 404 | SCRIPT_NOT_FOUND, BUILD_NOT_FOUND | No existe ese script en este proyecto, o ese build de este script. |
| 404 | KEY_SYSTEM_NOT_FOUND, STEP_NOT_FOUND, BLOCK_NOT_FOUND | No existe ese sistema de claves, paso o bloqueo en este proyecto. |
| 409 | ALREADY_BLOCKED | Esa cuenta de Discord ya está bloqueada en esta página. |
| 429 | TOO_MANY_BUILDS | El workspace ya tiene varios builds esperando. |
| 503 | UNAVAILABLE | La API no llega al servicio que sella y compila el código. |
| 503 | TEMPORARILY_UNAVAILABLE | No disponible temporalmente. Espera Retry-After: 30 antes de reintentar. |
| 404 | PROJECT_NOT_FOUND | No existe ese proyecto en este workspace. Un proyecto de otro workspace, uno eliminado y un id inventado responden igual. |
| 404 | NOT_FOUND | No existe esa clave en este proyecto. |
| 409 | KEY_EXISTS | Ya existe una clave con ese valor. |
| 409 | ALREADY_LINKED | La clave ya está vinculada a otra cuenta de Discord; envía force para reemplazarla. |
| 413 | TOO_LARGE | El cuerpo supera el límite de este endpoint. |
| 429 | RATE_LIMIT | Demasiadas 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.