Авторизация

После аутентификации mxHeadless проверяет право на действие в четыре шага:

1. Permission маршрута: публичный или нужен identity
2. Scope ключа или токена: строка вида {object}.{action}
3. MODX ACL: контекст, просмотр ресурса, view_unpublished
4. Field policy: hidden и protected поля

Нет нужного scope у API key / OAuth → 403 scope_denied.

Как проверяются scopes

Тип	Проверка
API key (mxh_*)	Список scopes ключа. Есть * → все действия
OAuth (mxt_*)	Scopes токена (пересечение с scopes клиента)
Session	modX->hasPermission() с той же строкой (resources.read и т.д.)
Anonymous	Только public GET. Scopes не задают

Для интеграций обычно хватает API key. Сессия удобна для mgr и UI на том же origin с CSRF.

Core scopes (фиксированные маршруты)

Scope	Маршруты
resources.read	GET /resources, GET /resources/{id}, GET /pages/{uri}
resources.create	POST /resources
resources.update	PUT / PATCH /resources/{id}
resources.delete	DELETE /resources/{id}
contexts.read	GET /contexts, GET /contexts/{key}, GET /contexts/{key}/settings
chunks.read	GET /chunks, GET /chunks/{id}
templates.read	GET /templates, GET /templates/{id}
snippets.read	GET /snippets, GET /snippets/{id}
tvs.read	GET /tvs, GET /tvs/{id}
categories.read	GET /categories, GET /categories/{id}
content_types.read	GET /content_types, GET /content_types/{id}
preview	?preview=true без view_unpublished у сессии. Также участвует в проверке include_deleted
fields.{field}	Поле из protectedFields объекта
*	Все scopes (только для ключей и токенов)

Meta-маршруты (/, /health, /schema, /docs, /meta/*) и POST /auth/token не требуют scope.

Scopes для /objects/{name}

Шаблон из кода: {name}.{action}, где {name} — имя в registry, не PHP-класс и не префикс objects..

Scope	Method	Path
{name}.read	GET	/objects/{name}, /objects/{name}/{id}
{name}.create	POST	/objects/{name}
{name}.update	PUT, PATCH	/objects/{name}/{id}
{name}.delete	DELETE	/objects/{name}/{id}

Примеры после регистрации MiniShop3-объектов:

Scope	Смысл
products.read	Каталог товаров
ms_categories.read	Категории товаров MS3. Core categories.read — элементы modCategory
orders.read	Заказы (обычно не public, плюс ACL)
orders.update	Обновление заказа, если object writable

Список зарегистрированных имён: GET /schema или GET /meta/endpoints на этом сайте.

Пример набора для ключа

Публичный фронт (только чтение контента) часто обходится без ключа.

CI / preview:

resources.read,preview,chunks.read,templates.read

Каталог MS3 + CMS:

resources.read,products.read,ms_categories.read

Admin API (узко, без *):

resources.read,resources.create,resources.update,orders.read

Создание ключа: API keys. OAuth: OAuth.

Public vs protected

Anonymous может читать discovery, health, schema, docs, meta, GET /resources и GET /pages/{uri} в рамках ACL опубликованных ресурсов.

Элементы, контексты, операции записи и /objects/* требуют учётных данных.

Контекст

Контекст запуска: mxheadless_context (по умолчанию web) задаёт контекст при инициализации MODX в шлюзе и api.php. Значение mgr игнорируется.

В запросе: заголовок X-Context или query ?context=. Значение должно входить в mxheadless_allowed_contexts (по умолчанию web,mgr). Иначе 422 Invalid context.

Мутации по id находят строку в любом контексте, затем проверяют доступ context.{key} / context_{key}. Запись context_key на неизвестный или незагружаемый контекст даёт 422, не 500.

Поля

Скрытые поля не попадают в JSON. Protected отдаются и записываются только при отдельном field-level праве: scope fields.{field} у ключа или токена, MODX-право mxheadless_fields_{field} у сессии. Запрос fields= на неизвестное или запрещённое поле даёт 422.

Право	Кто	Что открывает
fields.{field}	API key, OAuth	Поле {field} из protectedFields на чтение и запись
mxheadless_fields_{field}	Сессия MODX	То же для текущего пользователя
mxheadless_fields_all	Сессия MODX	Все protectedFields объекта

Поля из hiddenFields (properties у resources) не открываются никаким флагом: они вырезаются из ответа и запись в них даёт 422. Поля из immutableFields не пишутся даже с полным набором прав.

Поля из protectedFields у resources: createdby, editedby, deletedby, publishedby.

Preview и deleted

Query	Кто
preview=true	Session с view_unpublished или scope preview. Достаточно одного из двух: права пользователя-владельца ключа не проверяются
include_deleted=1	Не для anonymous. Нужны preview, resources.update, resources.delete, view_unpublished или empty_recycle_bin

См. также

• Каталог эндпоинтов
• Аутентификация