# Свои схемы аутентификации

Зарегистрируйте обработчик `integrate_api_authenticate`, чтобы добавить свою схему. Если `$idMember` остался `null`, применяется штатная проверка ключей. Заданный `$idMember` всё равно проходит проверку активации аккаунта и получает полный контекст прав SMF.

authenticate

```php
<?php declare(strict_types=1);

use SMF\API\Request;

// ...

public function authenticate(Request $request, ?int &$idMember): void
{
    $token = $request->header('x-my-oauth');

    if (! empty($token)) {
        $idMember = my_resolve_oauth_to_member((string) $token);
    }
}
```

Обработчик выполняется на каждом запросе, поэтому держите его быстрым. Он может и сам отклонить запрос: бросьте `ApiException` — и клиент получит JSON-ошибку вместо обычного `401`.

## Место в жизненном цикле запроса

1. Парсится запрос (`Request`).
2. Выполняются хуки `integrate_api_pre_dispatch` (лимиты, CORS-preflight).
3. Аутентификация: сначала все обработчики `integrate_api_authenticate`, затем штатная проверка API-ключа, если `$idMember` всё ещё `null`.
4. Роутер передаёт управление контроллеру.

## Штатные источники API-ключа (когда кастомный id не выставлен)

Встроенный аутентификатор принимает ключ из `Authorization: Bearer <key>`, заголовка `X-API-Key` или параметра запроса `api_key` — именно в таком порядке предпочтения. После аутентификации восстанавливается полный контекст пользователя SMF (`$user_info`, `allowedTo()`, `{query_see_board}`).

Ключ сверяется с картой, сохранённой в настройках мода, где каждый токен указывает на id пользователя. Отсутствующий ключ, неизвестный ключ и ключ, чей пользователь больше не существует или не полностью активирован (`is_activated = 1`), дают `401` с кодом ошибки `unauthorized`.

> [!NOTE]
>
> **Ключ принадлежит пользователю, а не набору прав**
>
> Сам по себе ключ никаких прав не несёт: запрос выполняется с правами пользователя, с которым он связан. Выдавайте клиенту ключ пользователя из группы с ровно теми правами, которые этому клиенту нужны.

## Рекомендации

- Преобразуйте токен в целочисленный id пользователя только если смогли его проверить; иначе оставляйте `$idMember` как `null` для fallback.
- Не выставляйте id для неактивного или забаненного аккаунта — проверка ядра всё равно его отклонит.
- Делайте обработчик быстрым — он выполняется на каждом запросе к API.
