Конвенции справочника

Общие понятия, на которые ссылаются страницы методов. Здесь — канон; на страницах методов даются только ссылки сюда.

Уровни доступа (middleware)

Каждый эндпоинт защищён одним или несколькими middleware (server/auth/middleware.js). В блоке инвентаря страницы метода поле Auth показывает их как есть из кода.

Middleware	Смысл
`optionalAuth`	Аноним (гость) и авторизованный допускаются. Гостю PG отдаёт только его guest-данные.
`requireAuth`	Только авторизованный пользователь (есть сессия-cookie или валидный токен).
`requireProjectAccess`	Загружает проект и проверяет доступ читателя; уровень (`read`/`write`) кладёт в `req.projectAccess`. Точную запись (owner/spaceman/org_admin) досматривает PG-функция.
`requireSiteAdmin`	Только site-admin с активной TOTP-сессией. Токену недоступно ни на одном scope.

Внутри write-хендлеров часто есть дополнительная проверка: для guest-спейса — заголовок X-Guest-Projects (claim на конкретный проект), для владельческих проектов — req.projectAccess === 'write'. Точные правила ролей — в матрице RP (источник истины разрешений) и в секции «Для человека» каждого метода.

Scope токена (агентный доступ)

Агент ходит под токеном владельца — с теми же правами, что у него в UI.

Scope	Что можно
`read`	Только `GET`.
`read_write`	`GET` + мутации (`POST`/`PUT`/`PATCH`/`DELETE`), в пределах роли владельца.

Никакому токену на любом scope недоступны site-admin-операции (by design). Часть org-admin write-операций в v1 закрыта на уровне agent-gate (server/auth/agentGate.js). Детали — в путеводителе для агента.

Формат ответа для агента

Cookie-клиент (браузер) всегда получает JSON.
Токен с Accept: text/markdown (или ?format=md) получает Markdown-зеркало ресурса (server/agent/negotiate.js). У ресурсов есть ETag; повтор с If-None-Match → 304 (экономия токенов).
Блок ## Actions в Markdown-ответе перечисляет только действия, доступные данному токену (его scope и роль владельца) — см. server/agent/affordances.js.

display label ≠ system key

Видимая надпись (заголовок H1, текст кнопки) — это отображение; слаг id:, имя PG-функции, ключ в коде — это системные ключи. Переименование надписи не меняет системный ключ, и наоборот. Слаги страниц — системные ключи: они постоянны, на них ссылаются снаружи.

Роли

Шесть ролей системы: guest, employee, spaceman (менеджер спейса), supervisor (наблюдатель, read-only), org_admin, site_admin. Подробно — roles.