Быстрый старт

Пять шагов: от установленного пакета до первого успешного вызова. Предполагается, что правило веб-сервера уже настроено — Обзор и установка.

1. Пользователь интеграции

API выполняет запросы от имени реального пользователя MODX и проверяет его права штатным механизмом. Поэтому первым делом заведите пользователя, от чьего имени будет работать интеграция (или возьмите существующего), и включите его в группу пользователей.

Отдельный пользователь под каждую интеграцию — не формальность: по нему в журнале видно, кто менял данные, и его блокировка мгновенно останавливает именно эту интеграцию.

2. Права

Пользователи → Управление правами → Access Controls → Namespace Access: выдайте группе доступ к namespace mxapi с политикой mxapiDefault.

Право load обязательно

В любой политике для namespace mxapi должно быть право load: MODX требует его при загрузке самого объекта namespace, до проверки права эндпоинта. Без load пользователь получает отказ при полностью корректных остальных правах. В готовой политике mxapiDefault оно уже есть — помнить об этом нужно при создании своей.

Подробнее, включая ловушку с authority роли, — Права доступа.

3. Клиент интеграции

Клиент — это машинная учётка поверх пользователя: своя пара ключей, свой набор scope и своё время жизни токена. Заводится в админке:

1. откройте страницу правки пользователя из шага 1 → вкладка «mxApi»;
2. Добавить → укажите название, выберите scope (они сгруппированы по источникам) и время жизни токена;
3. скопируйте client_key и client_secret — секрет показывается один раз.

Вкладка видна тем, у кого есть право save_user. Подробно про поля и перевыпуск секрета — Токены и аутентификация.

Можно и без клиента

Для ручной проверки достаточно логина и пароля пользователя MODX — шаг 3 тогда пропускается, а в шаге 4 используется grant_type=password. Для постоянной интеграции так делать не стоит: пароль живого пользователя окажется в настройках чужой системы, а его смена сломает обмен.

4. Токен

curl -X POST 'https://site.ru/mxapi/v1/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{
        "grant_type": "client_credentials",
        "client_id": "<client_key>",
        "client_secret": "<client_secret>",
        "scope": "meta.read"
      }'

В ответе — access_token, expires_in и выданные scope:

{
  "success": true,
  "data": {
    "access_token": "DfT2...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "expires_at": "2026-07-31T09:00:00+00:00",
    "scope": "meta.read",
    "user": {}
  }
}

Параметр scope обязателен, и запросить в нём можно только то, на что у пользователя есть права MODX.

5. Первый вызов

curl 'https://site.ru/mxapi/v1/meta/endpoints' \
  -H 'Authorization: Bearer <access_token>'

Ответ — каталог эндпоинтов сайта: маршруты, методы, scope, права и параметры. Это же видно глазами в админке (Компоненты → mxApi), а машиночитаемую спецификацию отдаёт GET /meta/openapi — Каталог и OpenAPI.

Если что-то не работает

Симптом	Причина
HTML-страница 404 сайта вместо JSON	не сработало правило веб-сервера — Маршрутизация
token_required при верном токене	до PHP не доходит заголовок Authorization (Apache) — Маршрутизация
invalid_credentials	неверные логин/пароль или client_id/client_secret; либо клиент отключён
invalid_scope	запрошен scope, которого нет ни у одного эндпоинта этого сайта
insufficient_permission	у пользователя нет права MODX — проверьте load и authority роли (Права)
insufficient_scope	scope есть на сайте, но не выдан этому клиенту

Полный список кодов — Токены и аутентификация → Коды ошибок.