Skip to main content
Каждый запрос к API Guard Forum должен содержать ключ в заголовке XF-Api-Key. Даже доступ с правами гостя требует ключа: гостевой контекст определяет разрешения, а не отменяет авторизацию.
YOUR_API_KEY — условное обозначение. В примерах для командной строки значение берётся из переменной окружения $FORUM_API_KEY на стороне сервера интеграции.

​
Получение ключа

В XenForo ключи создаются в панели администратора: Setup → API keys. По стандартным правилам XenForo этот раздел доступен суперадминистраторам; обычные пользователи не выпускают ключи самостоятельно. При создании ключа выбирают его тип и scopes — области API, к которым он получит доступ. Для интеграции стоит выдать отдельный ключ с минимальными правами, необходимыми для её задач.
Guard Forum использует XenForo 2.2.19. Доступность конкретного метода зависит от выданного ключа и пользовательского контекста.

​
Три типа ключей

Guest key подходит для интеграций с гостевым доступом. User key фиксирует пользователя, от имени которого работает приложение. Super user key позволяет серверной интеграции выбирать контекст для каждого запроса.
Выбирайте тип ключа по задаче. Если интеграции достаточно одного фиксированного пользователя, User key делает её права понятнее и не требует переключения контекста.

​
Пользовательский контекст

Для ключа типа super заголовок XF-Api-User задаёт ID пользователя, от имени которого выполняется запрос:
Условный пример заголовков
Здесь 123 — условный ID. Подставляйте ID пользователя, предусмотренного вашей интеграцией. Если XF-Api-User не передан, Super user key использует гостевой контекст. Сам тип super не означает, что каждый запрос автоматически выполняется с правами администратора. Для Guest key и User key контекст закреплён типом ключа; заголовок выбора пользователя предназначен для Super user key. Контекст важен и для чтения: пользователь может видеть только часть разделов форума. В операциях записи он также определяет автора действия, когда это предусмотрено методом.

​
Scopes и права пользователя

Проверяйте два независимых уровня доступа: Подходящий scope сам по себе не даёт пользователю доступ к закрытому разделу. И наоборот: права пользователя на форуме не заменяют отсутствующий scope ключа. Для обычного запроса нужны и подходящий scope, и разрешение пользовательского контекста. Ограничения конкретного метода смотрите в его справочнике.

​
Особая возможность Super user key

XenForo позволяет запросу с Super user key обойти права пользовательского контекста через параметр api_bypass_permissions=1. Его можно передать в query string или теле запроса. Это отдельная возможность конкретного запроса; она не включается автоматически из-за типа ключа.
Не добавляйте api_bypass_permissions=1 в общие настройки клиента. Используйте его только для явно предусмотренной серверной операции, которой действительно нужен обход прав. В обычных запросах сохраняйте проверку прав выбранного пользователя.
Флаг относится к правам пользовательского контекста. Scopes ключа оцениваются отдельно; возможность обхода прав не следует считать заменой настройки scopes.

​
Хранение и передача ключа

Держите ключ в серверной конфигурации или хранилище секретов интеграции. Не включайте его в браузерный JavaScript, публичный репозиторий, URL или журнал запросов. Передавайте ключ только в XF-Api-Key через HTTPS. Следующий пример получает список тем; ключу нужен scope thread:read. Предполагается, что переменная FORUM_API_KEY уже настроена в окружении; команда не выводит её значение:
При компрометации ключа перевыпустите его в панели администратора и обновите серверную конфигурацию интеграции. Заголовки с ключом исключайте из логов и диагностических отчётов.

Запросы и ошибки

Форматы данных, обработка HTTP-статусов и пример серверного клиента.

Механизм ключей XenForo

Официальное описание типов ключей, scopes и пользовательского контекста.