Аутентификация¶

API поддерживает три метода аутентификации, которые проверяются в таком порядке: ключ API, JWT, затем сессия. Запросы к публичным эндпоинтам (всё под /auth/, переводы, миниатюры и /ping) пропускают аутентификацию.

Ключи API¶

Рекомендуемый метод для интеграций между серверами и инструментов CLI.

Создание ключа:

bin/plugin api keys:generate --user=admin --name="CI Pipeline" --expiry=90

Использование в запросах:

# Через заголовок (предпочтительно)
curl -H "X-API-Key: grav_abc123..." https://my-site.example/api/v1/pages

# Через параметр запроса (удобно для быстрой проверки)
curl "https://my-site.example/api/v1/pages?api_key=grav_abc123..."

Ключи API хранятся в учётной записи пользователя в виде хешей bcrypt. У каждого ключа может быть необязательная дата истечения, отслеживается время последнего использования, а при создании через API ключ можно ограничить набором областей действия разрешений.

Управление ключами¶

• Список ключей: bin/plugin api keys:list --user=admin
• Отзыв ключа: bin/plugin api keys:revoke key_id --user=admin (не указывайте ID ключа, чтобы выбрать его из списка)
• Ключами также можно управлять через интерфейс Admin на странице профиля каждого пользователя

JWT-токены¶

Лучший вариант для приложений в браузере, таких как Admin2.

Получение токенов:

curl -X POST https://my-site.example/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'

Ответ:

{
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": { "username": "admin", "fullname": "Admin", "email": "admin@example.com", "super_admin": true, "access": { } }
  }
}

Если в учётной записи включена двухфакторная аутентификация, ответ содержит кратковременный запрос на подтверждение вместо токенов (requires_2fa: true, challenge_token, token_type: "Challenge"). Отправьте токен запроса и код на POST /auth/2fa/verify, чтобы получить пару токенов.

Использование в запросах:

# Рекомендуется: X-API-Token (устойчив к удалению заголовка Authorization в FastCGI / PHP-FPM)
curl -H "X-API-Token: eyJ..." https://my-site.example/api/v1/pages

# Также принимается: стандартный Authorization: Bearer
curl -H "Authorization: Bearer eyJ..." https://my-site.example/api/v1/pages

Обновление истёкших токенов:

curl -X POST https://my-site.example/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJ..."}'

Проброс сессии¶

Если у пользователя уже есть активная сессия Grav (например, он вошёл в админку), API автоматически принимает эту сессию. В основном это используется административным интерфейсом для бесшовной интеграции.

Поскольку браузер отправляет cookie сессии с любым запросом к сайту, включая форму, отправленную с другого сайта, операция записи (POST, PUT, PATCH или DELETE), авторизованная только через cookie сессии, должна подтвердить, что она пришла с вашего собственного сайта. Её заголовок Origin (или Referer, если Origin отсутствует) должен указывать на этот хост или на источник из списка cors.origins. Если нет ни того, ни другого заголовка, запрос должен иметь тип содержимого JSON или собственный заголовок, например X-Requested-With. В противном случае API отвечает 403. Чтение это не затрагивает, вызовы fetch() с того же источника проходят как есть, а ключи API и JWT такой проверке никогда не подвергаются. На публичном маршруте операция записи, не прошедшая эту проверку, рассматривается как запрос гостя, а не отклоняется.

Права доступа¶

API использует собственное пространство имён разрешений, отдельное от разрешений админки:

Выдавайте разрешения пользователям через конфигурацию access их учётной записи:

access:
  api:
    access: true
    pages:
      read: true
      write: true
    media:
      read: true
      write: true