LuawardDocs

Обзор Developer API

Аутентификация запросов, лимиты и управление проектами и лицензионными ключами воркспейса.

Базовый URL

Developer API обслуживает edge-хост Luaward:

https://api.luaward.com/v3

Используйте api.luaward.com для API v3. Загрузчики остаются на luaward.com, страницы ключей — на key.luaward.com. Свои домены пока недоступны.

Официальные пакеты для JavaScript/TypeScript (npm @luaward/sdk), Python (PyPI luaward) и CLI (npm @luaward/cli) уже доступны в публичных реестрах. Команды установки и правила работы с токенами описаны в разделе SDK и CLI и на github.com/luaward. Расширение VS Code ещё не опубликовано в Marketplace; обратитесь в поддержку за проверенным артефактом.

Создание API-ключа

Откройте Dashboard → API для разработчиков и создайте ключ с названием. Ключ показывается один раз. Luaward хранит только его хеш, поэтому скопируйте ключ в хранилище секретов на сервере и никогда не помещайте его в скрипт, браузерный бандл или публичный репозиторий.

Ключ принадлежит воркспейсу, а не одному проекту, как единый ключ аккаунта в Luarmor: он читает и меняет все проекты воркспейса и может создавать новые. В воркспейсе может быть до 10 активных ключей. Создавать, отзывать и удалять ключи может только владелец воркспейса или администратор. Отозванный ключ перестаёт работать сразу.

При создании ключа вы выбираете, что он может: Полный доступ (всё, сейчас и по мере роста API), Управление ключами (чтение, а также создание, изменение, удаление, сброс, бан и разбан лицензионных ключей игроков) или Только чтение. Ключ можно ограничить несколькими проектами: тогда он видит только их (любой другой проект отвечает 404 PROJECT_NOT_FOUND, как будто его нет), статистика считает только их, и он не может создавать новые проекты. Вызов, который ключу не разрешён, отвечает 403 INSUFFICIENT_SCOPE. Что ключ может и до каких проектов дотягивается, задаётся при создании; чтобы изменить, создайте новый ключ и отзовите старый. У скриптов и систем ключей свои scope — scripts:write и keysystem:write: Полный доступ их включает, Управление ключами — нет.

Аутентификация

Передавайте ключ разработчика в заголовке Authorization:

Authorization: Bearer YOUR_DEVELOPER_API_KEY

API также принимает заголовок api-key. В адресе (например, как query-параметр) ключ не принимается никогда, потому что адреса попадают в логи.

Ограничения

ЧтоОграничение
Запросов на ключ60 в минуту. Больше — HTTP 429 с заголовком Retry-After.
Неверных ключей с одного адреса30 в минуту. Затем адрес ждёт минуту (429).
Тело запросаПо умолчанию: 16 KiB. Исходники скриптов: 4 MiB; пакетные операции с ключами: 512 KiB. Превышение возвращает 413.
Лицензионные ключиКлючи, созданные через API, учитываются в лимите ключей вашего плана вместе с созданными в дашборде. На лимите создание возвращает 403 с PLAN_LIMIT.
ПроектыПроекты, созданные через API, так же учитываются в лимите проектов вашего плана (403 с PLAN_LIMIT).

Разрешённые IP

Воркспейс может разрешить адреса, с которых к его API можно обращаться (Dashboard → API для разработчиков → Разрешённые IP: до 20 полных адресов IPv4 или IPv6, у каждого заметка-напоминание). Один список действует для всех ключей и всех проектов воркспейса. Если список пуст, вызывать может любой адрес. Если в нём есть адреса, то только они, каким бы ключом ни пользовались. Диапазоны вроде 10.0.0.0/8 не поддерживаются, а вызывающий с нечитаемым адресом считается не входящим в список. После сохранения дашборд показывает адрес со скрытым окончанием, поэтому узнавать его помогает заметка. Изменение действует со следующего вызова.

Когда вызов отклонён

Ошибка отвечает success: false, фразой в error и code, который может прочитать программа.

СтатусКодЗначение
400INVALID_BODY, INVALID_FIELDТело не JSON, либо поле нарушает правило. INVALID_FIELD добавляет список details с каждым полем.
400CONFIRM_REQUIREDДля удаления проекта нужно точное название в confirm_name.
401UNAUTHORIZEDКлюча нет, он неверный или отозван.
403SUSPENDEDАккаунт владельца воркспейса приостановлен.
403IP_NOT_ALLOWEDАдреса нет в списке разрешённых IP воркспейса.
403PLAN_LIMITВоркспейс достиг лимита ключей или проектов.
403INSUFFICIENT_SCOPEКлючу это не разрешено: он только для чтения, управляет ключами, но не проектами, или ограничен несколькими проектами и пытался создать проект.
400BUILD_NOT_READYОтдавать можно только завершённую сборку.
403SCRIPT_LOCKEDLuaward выключил этот скрипт; здесь его не включить.
404SCRIPT_NOT_FOUND, BUILD_NOT_FOUNDНет такого скрипта в этом проекте или такой сборки у этого скрипта.
404KEY_SYSTEM_NOT_FOUND, STEP_NOT_FOUND, BLOCK_NOT_FOUNDВ этом проекте нет такой системы ключей, шага или блокировки.
409ALREADY_BLOCKEDЭтот аккаунт Discord уже заблокирован на этой странице.
429TOO_MANY_BUILDSВ воркспейсе уже несколько сборок в очереди.
503UNAVAILABLEAPI не может связаться со службой, которая шифрует и собирает код.
503TEMPORARILY_UNAVAILABLEВременно недоступно. Перед повтором подождите Retry-After: 30.
404PROJECT_NOT_FOUNDТакого проекта нет в этом воркспейсе. Проект другого воркспейса, удалённый проект и выдуманный id отвечают одинаково.
404NOT_FOUNDВ этом проекте нет такого ключа.
409KEY_EXISTSКлюч с таким значением уже существует.
409ALREADY_LINKEDКлюч уже привязан к другому аккаунту Discord; отправьте force, чтобы заменить.
413TOO_LARGEТело превышает лимит этого endpoint.
429RATE_LIMITСлишком много запросов или слишком много неверных ключей с одного адреса.

Что записывается

Изменения через API видны в истории лицензионного ключа с действующим лицом api: и названием API-ключа: created, extended, hwid_reset, banned, unbanned. История удалённого ключа уходит вместе с ним, поэтому удаление записывается в журнал аудита воркспейса. Создание, переименование и удаление проекта тоже записываются туда и видны в ленте активности дашборда. Ответы никогда не кэшируются (Cache-Control: no-store).

Доступные операции

API управляет проектами, скриптами (код, сборки и главный выключатель), лицензионными ключами по одному и массово и системой ключей, а также читает статистику, последние запуски, журнал аудита и участников. См. справочник API, API скриптов, Массовые операции и экспорт, Статистика, запуски и журнал и API системы ключей.