Обзор 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_KEYAPI также принимает заголовок 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, который может прочитать программа.
| Статус | Код | Значение |
|---|---|---|
| 400 | INVALID_BODY, INVALID_FIELD | Тело не JSON, либо поле нарушает правило. INVALID_FIELD добавляет список details с каждым полем. |
| 400 | CONFIRM_REQUIRED | Для удаления проекта нужно точное название в confirm_name. |
| 401 | UNAUTHORIZED | Ключа нет, он неверный или отозван. |
| 403 | SUSPENDED | Аккаунт владельца воркспейса приостановлен. |
| 403 | IP_NOT_ALLOWED | Адреса нет в списке разрешённых IP воркспейса. |
| 403 | PLAN_LIMIT | Воркспейс достиг лимита ключей или проектов. |
| 403 | INSUFFICIENT_SCOPE | Ключу это не разрешено: он только для чтения, управляет ключами, но не проектами, или ограничен несколькими проектами и пытался создать проект. |
| 400 | BUILD_NOT_READY | Отдавать можно только завершённую сборку. |
| 403 | SCRIPT_LOCKED | Luaward выключил этот скрипт; здесь его не включить. |
| 404 | SCRIPT_NOT_FOUND, BUILD_NOT_FOUND | Нет такого скрипта в этом проекте или такой сборки у этого скрипта. |
| 404 | KEY_SYSTEM_NOT_FOUND, STEP_NOT_FOUND, BLOCK_NOT_FOUND | В этом проекте нет такой системы ключей, шага или блокировки. |
| 409 | ALREADY_BLOCKED | Этот аккаунт Discord уже заблокирован на этой странице. |
| 429 | TOO_MANY_BUILDS | В воркспейсе уже несколько сборок в очереди. |
| 503 | UNAVAILABLE | API не может связаться со службой, которая шифрует и собирает код. |
| 503 | TEMPORARILY_UNAVAILABLE | Временно недоступно. Перед повтором подождите Retry-After: 30. |
| 404 | PROJECT_NOT_FOUND | Такого проекта нет в этом воркспейсе. Проект другого воркспейса, удалённый проект и выдуманный id отвечают одинаково. |
| 404 | NOT_FOUND | В этом проекте нет такого ключа. |
| 409 | KEY_EXISTS | Ключ с таким значением уже существует. |
| 409 | ALREADY_LINKED | Ключ уже привязан к другому аккаунту Discord; отправьте force, чтобы заменить. |
| 413 | TOO_LARGE | Тело превышает лимит этого endpoint. |
| 429 | RATE_LIMIT | Слишком много запросов или слишком много неверных ключей с одного адреса. |
Что записывается
Изменения через API видны в истории лицензионного ключа с действующим лицом api: и названием API-ключа: created, extended, hwid_reset, banned, unbanned. История удалённого ключа уходит вместе с ним, поэтому удаление записывается в журнал аудита воркспейса. Создание, переименование и удаление проекта тоже записываются туда и видны в ленте активности дашборда. Ответы никогда не кэшируются (Cache-Control: no-store).
Доступные операции
API управляет проектами, скриптами (код, сборки и главный выключатель), лицензионными ключами по одному и массово и системой ключей, а также читает статистику, последние запуски, журнал аудита и участников. См. справочник API, API скриптов, Массовые операции и экспорт, Статистика, запуски и журнал и API системы ключей.