LuawardDocs

Visão geral da API para desenvolvedores

Autentique solicitações, entenda limites e gerencie os projetos e as chaves de licença do workspace.

URL base

A Developer API é servida pelo host de borda (edge) do Luaward:

https://api.luaward.com/v3

Use api.luaward.com para a API v3. Loaders ficam em luaward.com e páginas de chave em key.luaward.com. Domínios personalizados ainda não estão disponíveis.

Os pacotes oficiais de JavaScript/TypeScript (npm @luaward/sdk), Python (PyPI luaward) e a CLI (npm @luaward/cli) já estão publicados nos registros públicos. Veja SDKs e CLI e github.com/luaward para comandos de instalação e credenciais. A extensão para VS Code ainda não está no Marketplace; fale com o suporte para obter um artefato testado.

Criar uma chave de API

Abra Dashboard → API para desenvolvedores e crie uma chave com nome. A chave é mostrada uma única vez. O Luaward guarda apenas o hash dela, então copie-a para um cofre de segredos no servidor e nunca a coloque em um script, em um bundle de navegador ou em um repositório público.

Uma chave pertence ao workspace, não a um projeto, como a chave única da conta no Luarmor: ela lê e altera todos os projetos do workspace e pode criar novos. Um workspace pode ter até 10 chaves ativas. Só o dono do workspace ou um administrador pode criar, revogar ou excluir chaves. Uma chave revogada para de funcionar na hora.

Ao criar uma chave, você escolhe o que ela pode fazer: Acesso total (tudo, hoje e conforme a API crescer), Gerenciar chaves (ler e criar, alterar, excluir, redefinir, banir e desbanir as chaves de licença dos jogadores) ou Somente leitura. Também é possível limitar uma chave a alguns projetos: ela passa a ver só esses (qualquer outro projeto responde 404 PROJECT_NOT_FOUND, como se não existisse), as estatísticas contam só eles e ela não cria novos projetos. Uma chamada que a chave não pode fazer responde 403 INSUFFICIENT_SCOPE. O que a chave pode fazer e quais projetos ela alcança são definidos na criação; para mudar, crie outra chave e revogue a antiga. Scripts e sistemas de chaves têm escopos próprios, scripts:write e keysystem:write: Acesso total os inclui, Gerenciar chaves não.

Autenticar

Envie a chave de desenvolvedor no cabeçalho Authorization:

Authorization: Bearer YOUR_DEVELOPER_API_KEY

A API também aceita um cabeçalho api-key. A chave nunca é aceita no endereço (por exemplo, como parâmetro de consulta), porque os endereços vão parar em logs.

Limites

O quêLimite
Requisições por chave60 por minuto. Acima disso: HTTP 429 com o cabeçalho Retry-After.
Chaves erradas de um mesmo endereço30 por minuto. Depois o endereço espera um minuto (429).
Corpo da requisiçãoPadrão: 16 KiB. Código de scripts: 4 MiB; chaves em lote: 512 KiB. Corpos maiores retornam 413.
Chaves de licençaAs chaves criadas pela API contam no limite de chaves do seu plano, junto com as criadas no dashboard. No limite, criar retorna 403 com PLAN_LIMIT.
ProjetosOs projetos criados pela API contam no limite de projetos do seu plano da mesma forma (403 com PLAN_LIMIT).

IPs permitidos

O workspace pode permitir os endereços de onde sua API pode ser chamada (Dashboard → API para desenvolvedores → IPs permitidos: até 20 endereços completos IPv4 ou IPv6, cada um com uma nota de lembrete). Uma só lista vale para todas as chaves e todos os projetos do workspace. Sem nenhum listado, qualquer endereço pode chamar. Com algum listado, só esses podem, seja qual for a chave usada. Faixas como 10.0.0.0/8 não são aceitas, e quem chama com um endereço que não pode ser lido não está na lista. Depois de salvo, o dashboard mostra o endereço com o final oculto, então a nota é como você o reconhece. A mudança vale na próxima chamada.

Quando uma chamada é recusada

Um erro responde com success: false, uma frase em error e um code que um programa consegue ler.

StatusCódigoSignificado
400INVALID_BODY, INVALID_FIELDO corpo não é JSON ou um campo quebra uma regra. INVALID_FIELD traz uma lista details com cada campo.
400CONFIRM_REQUIREDExcluir um projeto exige o nome exato em confirm_name.
401UNAUTHORIZEDA chave está ausente, errada ou revogada.
403SUSPENDEDA conta do dono do workspace está suspensa.
403IP_NOT_ALLOWEDO endereço não está na lista de IPs permitidos do workspace.
403PLAN_LIMITO workspace atingiu o limite de chaves ou de projetos.
403INSUFFICIENT_SCOPEA chave não pode fazer isto: é somente leitura, gerencia chaves mas não projetos, ou está limitada a alguns projetos e tentou criar um projeto.
400BUILD_NOT_READYSó um build concluído pode ser servido.
403SCRIPT_LOCKEDO Luaward desligou este script; ele não pode ser ligado aqui.
404SCRIPT_NOT_FOUND, BUILD_NOT_FOUNDNão há esse script neste projeto, ou esse build deste script.
404KEY_SYSTEM_NOT_FOUND, STEP_NOT_FOUND, BLOCK_NOT_FOUNDNão há esse sistema de chaves, etapa ou bloqueio neste projeto.
409ALREADY_BLOCKEDEssa conta do Discord já está bloqueada nesta página.
429TOO_MANY_BUILDSO workspace já tem vários builds esperando.
503UNAVAILABLEA API não alcança o serviço que sela e compila o código.
503TEMPORARILY_UNAVAILABLETemporariamente indisponível. Aguarde Retry-After: 30 antes de tentar novamente.
404PROJECT_NOT_FOUNDNão há esse projeto neste workspace. Um projeto de outro workspace, um excluído e um id inventado respondem igual.
404NOT_FOUNDNão há essa chave neste projeto.
409KEY_EXISTSJá existe uma chave com esse valor.
409ALREADY_LINKEDA chave já está vinculada a outra conta do Discord; envie force para substituir.
413TOO_LARGEO corpo excede o limite deste endpoint.
429RATE_LIMITRequisições demais, ou chaves erradas demais de um mesmo endereço.

O que fica registrado

As alterações feitas pela API aparecem no histórico da chave de licença com o autor api: seguido do nome da chave de API: created, extended, hwid_reset, banned, unbanned. O histórico de uma chave excluída vai junto com ela, então a exclusão fica registrada no log de auditoria do workspace. Criar, renomear e excluir um projeto também ficam registrados ali e aparecem no feed de atividade do dashboard. As respostas nunca são guardadas em cache (Cache-Control: no-store).

Operações disponíveis

A API gerencia projetos, scripts (código, builds e a chave geral), chaves de licença uma a uma ou em massa e o sistema de chaves, e lê estatísticas, execuções recentes, o log de auditoria e os membros. Veja a referência da API, API de scripts, Chaves em massa e exportação, Estatísticas, execuções e registro e a API do sistema de chaves.