> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arzguard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Авторизация и права доступа

> Типы ключей XenForo, заголовки авторизации, пользовательский контекст и области доступа к API Guard Forum.

Каждый запрос к API Guard Forum должен содержать ключ в заголовке `XF-Api-Key`. Даже доступ с правами гостя требует ключа: гостевой контекст определяет разрешения, а не отменяет авторизацию.

```http theme={null}
XF-Api-Key: YOUR_API_KEY
```

`YOUR_API_KEY` — условное обозначение. В примерах для командной строки значение берётся из переменной окружения `$FORUM_API_KEY` на стороне сервера интеграции.

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

В XenForo ключи создаются в панели администратора: **Setup → API keys**. По стандартным правилам XenForo этот раздел доступен суперадминистраторам; обычные пользователи не выпускают ключи самостоятельно.

При создании ключа выбирают его тип и scopes — области API, к которым он получит доступ. Для интеграции стоит выдать отдельный ключ с минимальными правами, необходимыми для её задач.

<Note>
  Guard Forum использует XenForo 2.2.19. Доступность конкретного метода зависит от выданного ключа и пользовательского контекста.
</Note>

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

| Тип | Обозначение | От чьего имени выполняется запрос | Проверка прав |
| - | - | - | - |
| Guest key | `guest` | Гость форума | Применяются права гостя |
| User key | `user` | Пользователь, к которому привязан ключ | Применяются права этого пользователя |
| Super user key | `super` | Пользователь из `XF-Api-User`; без этого заголовка — гость | Обычно применяются права выбранного контекста; отдельно доступна возможность обхода прав |

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

<Tip>
  Выбирайте тип ключа по задаче. Если интеграции достаточно одного фиксированного пользователя, User key делает её права понятнее и не требует переключения контекста.
</Tip>

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

Для ключа типа `super` заголовок `XF-Api-User` задаёт ID пользователя, от имени которого выполняется запрос:

```http Условный пример заголовков theme={null}
XF-Api-Key: YOUR_SUPER_USER_API_KEY
XF-Api-User: 123
```

Здесь `123` — условный ID. Подставляйте ID пользователя, предусмотренного вашей интеграцией.

Если `XF-Api-User` не передан, Super user key использует **гостевой контекст**. Сам тип `super` не означает, что каждый запрос автоматически выполняется с правами администратора. Для Guest key и User key контекст закреплён типом ключа; заголовок выбора пользователя предназначен для Super user key.

Контекст важен и для чтения: пользователь может видеть только часть разделов форума. В операциях записи он также определяет автора действия, когда это предусмотрено методом.

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

Проверяйте два независимых уровня доступа:

| Уровень | Что ограничивает | Пример проверки |
| - | - | - |
| Scopes ключа | Доступ к областям и методам API | Разрешён ли ключу нужный метод |
| Права контекста | Доступ пользователя или гостя к данным и действиям форума | Видит ли выбранный пользователь нужный раздел |

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

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

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

XenForo позволяет запросу с Super user key обойти права пользовательского контекста через параметр `api_bypass_permissions=1`. Его можно передать в query string или теле запроса. Это отдельная возможность конкретного запроса; она не включается автоматически из-за типа ключа.

<Warning>
  Не добавляйте `api_bypass_permissions=1` в общие настройки клиента. Используйте его только для явно предусмотренной серверной операции, которой действительно нужен обход прав. В обычных запросах сохраняйте проверку прав выбранного пользователя.
</Warning>

Флаг относится к правам пользовательского контекста. Scopes ключа оцениваются отдельно; возможность обхода прав не следует считать заменой настройки scopes.

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

Держите ключ в серверной конфигурации или хранилище секретов интеграции. Не включайте его в браузерный JavaScript, публичный репозиторий, URL или журнал запросов. Передавайте ключ только в `XF-Api-Key` через HTTPS.

Следующий пример получает список тем; ключу нужен scope `thread:read`. Предполагается, что переменная `FORUM_API_KEY` уже настроена в окружении; команда не выводит её значение:

```bash theme={null}
curl --silent --show-error \
  --header "XF-Api-Key: $FORUM_API_KEY" \
  --header 'Accept: application/json' \
  'https://forum.arzguard.com/api/threads/?page=1'
```

При компрометации ключа перевыпустите его в панели администратора и обновите серверную конфигурацию интеграции. Заголовки с ключом исключайте из логов и диагностических отчётов.

<CardGroup cols={2}>
  <Card title="Запросы и ошибки" icon="code" href="/guard-forum/requests-and-errors">
    Форматы данных, обработка HTTP-статусов и пример серверного клиента.
  </Card>

  <Card title="Механизм ключей XenForo" icon="book-open" href="https://docs.xenforo.com/manual/reference/rest-api#api-keys">
    Официальное описание типов ключей, scopes и пользовательского контекста.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.