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/v3Use 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_KEYA 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 chave | 60 por minuto. Acima disso: HTTP 429 com o cabeçalho Retry-After. |
| Chaves erradas de um mesmo endereço | 30 por minuto. Depois o endereço espera um minuto (429). |
| Corpo da requisição | Padrão: 16 KiB. Código de scripts: 4 MiB; chaves em lote: 512 KiB. Corpos maiores retornam 413. |
| Chaves de licença | As 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. |
| Projetos | Os 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.
| Status | Código | Significado |
|---|---|---|
| 400 | INVALID_BODY, INVALID_FIELD | O corpo não é JSON ou um campo quebra uma regra. INVALID_FIELD traz uma lista details com cada campo. |
| 400 | CONFIRM_REQUIRED | Excluir um projeto exige o nome exato em confirm_name. |
| 401 | UNAUTHORIZED | A chave está ausente, errada ou revogada. |
| 403 | SUSPENDED | A conta do dono do workspace está suspensa. |
| 403 | IP_NOT_ALLOWED | O endereço não está na lista de IPs permitidos do workspace. |
| 403 | PLAN_LIMIT | O workspace atingiu o limite de chaves ou de projetos. |
| 403 | INSUFFICIENT_SCOPE | A 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. |
| 400 | BUILD_NOT_READY | Só um build concluído pode ser servido. |
| 403 | SCRIPT_LOCKED | O Luaward desligou este script; ele não pode ser ligado aqui. |
| 404 | SCRIPT_NOT_FOUND, BUILD_NOT_FOUND | Não há esse script neste projeto, ou esse build deste script. |
| 404 | KEY_SYSTEM_NOT_FOUND, STEP_NOT_FOUND, BLOCK_NOT_FOUND | Não há esse sistema de chaves, etapa ou bloqueio neste projeto. |
| 409 | ALREADY_BLOCKED | Essa conta do Discord já está bloqueada nesta página. |
| 429 | TOO_MANY_BUILDS | O workspace já tem vários builds esperando. |
| 503 | UNAVAILABLE | A API não alcança o serviço que sela e compila o código. |
| 503 | TEMPORARILY_UNAVAILABLE | Temporariamente indisponível. Aguarde Retry-After: 30 antes de tentar novamente. |
| 404 | PROJECT_NOT_FOUND | Não há esse projeto neste workspace. Um projeto de outro workspace, um excluído e um id inventado respondem igual. |
| 404 | NOT_FOUND | Não há essa chave neste projeto. |
| 409 | KEY_EXISTS | Já existe uma chave com esse valor. |
| 409 | ALREADY_LINKED | A chave já está vinculada a outra conta do Discord; envie force para substituir. |
| 413 | TOO_LARGE | O corpo excede o limite deste endpoint. |
| 429 | RATE_LIMIT | Requisiçõ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.