REST API: аутентификация и использование

Last updated on Jun 24, 2026 01:45

PolyCMS предлагает комплексный RESTful API «из коробки», позволяющий создавать безголовые интерфейсы, мобильные приложения или интегрироваться со сторонними инструментами (такими как Zapier, CRM или ERP-системы).

API расположен по префиксу /api/v1.

Система аутентификации

PolyCMS использует Laravel Sanctum для управления аутентификацией API. Он поддерживает два основных метода в зависимости от вашего варианта использования:

Аутентификация SPA (файлы cookie): используется встроенной панелью администратора Vue 3. Он опирается на сеансовые файлы cookie и защиту CSRF.

Аутентификация по токену API: используется для внешних приложений, мобильных приложений и модулей «Sandbox Remote». Этот метод использует токены на предъявителя.

В этом руководстве основное внимание уделяется Аутентификации токена API для внешней интеграции.

graph TD Client[Клиент отправляет HTTP-запрос] --> HeaderCheck{Есть заголовок Authorization?} HeaderCheck -->|Нет| Unauth[Возврат 401 Unauthorized] HeaderCheck -->|Да| Extract[Извлечение токена Bearer] Extract --> QueryDB[Запрос в БД для проверки токенов доступа] QueryDB --> TokenCheck{Токен существует и не истек?} TokenCheck -->|Нет| Unauth TokenCheck -->|Да| ResolveUser[Идентификация аутентифицированного пользователя] ResolveUser --> PermissionCheck[Проверка прав доступа и областей действия] PermissionCheck --> AuthCheck{Доступ разрешен?} AuthCheck -->|Нет| Forbidden[Возврат 403 Forbidden] AuthCheck -->|Да| Process[Выполнение логики эндпоинта] Process --> SuccessResponse[Возврат ответа в формате JSON]

Генерация токена личного доступа (PAT)

Для доступа к защищенным конечным точкам необходимо сгенерировать токен.

Войдите в панель администратора PolyCMS.

Перейдите в Настройки > Токены API (или нажмите на свой профиль пользователя).

Нажмите Создать новый токен.

Дайте токену узнаваемое имя (например, «Мобильное приложение» или «Интеграция Zapier»).

Важный шаг: текстовый токен будет показан только один раз*. Немедленно скопируйте его и сохраните в безопасном менеджере паролей.

Выполнение запросов к API

Получив токен, вы должны включить его в заголовок Authorization каждого HTTP-запроса, который вы отправляете к API PolyCMS.

Пример: получение текущего пользователя (cURL)

curl -X GET https://polycms.org/api/v1/user \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_PLAIN_TEXT_TOKEN_HERE"

Пример: создание публикации (JavaScript/Fetch)

const response = await fetch('https://polycms.org/api/v1/posts', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_PLAIN_TEXT_TOKEN_HERE'
  },
  body: JSON.stringify({
    title: 'Hello via API',
    slug: 'hello-via-api',
    content_raw: '{"blocks":[{"type":"paragraph","data":{"text":"Created via REST!"}}]}',
    status: 'draft'
  })
});

const data = await response.json();
console.log(data);

Лучшие практики безопасности

Только HTTPS: Всегда отправляйте запросы API через безопасное соединение https://. Отправка токенов Bearer через HTTP подвергает вашу систему перехвату.

Отзыв токена. Если вы подозреваете, что токен был скомпрометирован, немедленно отзовите его в панели администратора в разделе Настройки > Токены API.

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