PearCMS Docs v2.4
Документация / Мобильный клиент / REST API для разработчиков

REST API для разработчиков

PearCMS отдаёт REST API на /api/v1/admin/* для нативного Android-приложения админа. Авторизация по Bearer-токену с поддержкой 2FA, PIN и refresh. Все эндпоинты модулей проходят через единый диспатчер.

Актуально для v2.4 Обновлено 1 июля 2026

Авторизация #

Логин — обычный login + password. Если у юзера включён 2FA или PIN, сервер выдаёт «pending»-токен с особым скоупом и просит ввести код:

МетодURLНазначение
POST/api/v1/admin/auth/loginЛогин/пароль → access-токен или pending-токен
POST/api/v1/admin/auth/2faПодтверждение TOTP-кодом
POST/api/v1/admin/auth/pinПодтверждение 4-значным PIN’ом
POST/api/v1/admin/auth/refreshПродление токена
POST/api/v1/admin/auth/logoutОтзыв токена
POST /api/v1/admin/auth/loginjson
// Request
{ "login": "alice", "password": "…", "device": "Pixel 8" }

// Response (если 2FA не нужно)
{
    "ok": true,
    "token": "eyJh…",
    "expires_at": "2026-07-15T10:00:00Z",
    "user": { "id": 42, "login": "alice", "flags": "abc", "role": "" }
}

Все последующие запросы — с заголовком Authorization: Bearer <token>.

Профиль и discover #

МетодURLОписание
GET/api/v1/admin/meТекущий пользователь, его флаги и группы
GET/api/v1/admin/discoverДоступные модули, пункты меню, конфиг приложения
GET/api/v1/admin/pingHealth-check — для мониторинга и keep-alive

/discover мобильный клиент дергает один раз после логина и кеширует: оттуда он узнает какие модули включены и какие иконки рисовать.

Универсальный диспатчер #

Все эндпоинты модулей идут через один URL-шаблон:

Диспатчер модулейtext
/api/v1/admin/{module}/{action}    # GET / POST / PUT / DELETE / PATCH

Например, список баннеров: GET /api/v1/admin/Banner/list. Модуль регистрирует свои action’ы в собственном AdminApi/<Name>AdminApi.php через интерфейс AdminApiPanelInterface:

app/Modules/Users/AdminApi/UsersAdminApi.phpphp
public function endpoints(): array
{
    return [
        'list'   => ['method' => 'GET',  'flag' => 'manage', 'handler' => [$this, 'list']],
        'create' => ['method' => 'POST', 'flag' => 'manage',
                       'params' => ['login' => 'string', 'password' => 'string'],
                       'handler' => [$this, 'create']],
        // …
    ];
}

Права и проверка #

DispatchController для каждого запроса:

  1. Резолвит токен — узнаёт user_id, его личные флаги и union-флаги групп
  2. Эти данные через primeSessionFromCtx() кладутся в $_SESSION, чтобы Auth::flags() работал так же, как в браузерной сессии
  3. Берёт из спеки эндпоинта flag — это action_key для FlagsPanel модуля
  4. Вызывает module_can($module, $flag); если нет — 403 Forbidden с телом {"flag":"<имя>"}

Тот же admin, что сидит в браузерной панели, ходит через REST с теми же правами.

Управление токенами #

Раздел REST API (/s-panel/api) в админке показывает все выпущенные токены, их устройства, IP, last_used. Можно отозвать любой одним кликом или почистить просроченные пакетом.

Также там настройки модуля Api — TTL access-токена, лимиты на rate limiting, и журнал ошибок аутентификации.

Если что-то ломаетсяПри непонятных 403 в мобильном клиенте — первым делом загляните в журнал /s-panel/api: там видно, на каком action и каком флаге упала проверка.