# Custom Authentication Schemes

Register an `integrate_api_authenticate` handler to add your own scheme. If `$idMember` stays `null`, the native key check applies. A set `$idMember` still goes through the account activation check and receives the full SMF permission context.

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);
    }
}
```

The handler runs on every request, so keep it fast. It may also reject the request itself: throw an `ApiException` and the answer is a JSON error instead of the usual `401`.

## Where this fits in the request lifecycle

1. Request is parsed (`Request`).
2. `integrate_api_pre_dispatch` hooks run (throttling, CORS preflight).
3. Authentication runs: first all `integrate_api_authenticate` handlers, then the native API-key check if `$idMember` is still `null`.
4. Router dispatches to the controller.

## Native API-key sources (when no custom id is set)

The built-in authenticator accepts the key from `Authorization: Bearer <key>`, the `X-API-Key` header, or the `api_key` request parameter — in that order of preference. After authentication the full SMF user context is restored (`$user_info`, `allowedTo()`, `{query_see_board}`).

The key is matched against the map stored in the mod settings, where each token points to a member id. A missing key, an unknown key and a key whose member no longer exists or is not fully activated (`is_activated = 1`) all answer `401` with the error code `unauthorized`.

> [!NOTE]
>
> **Keys belong to members, not to permissions**
>
> A key carries no rights of its own: the request acts with the permissions of the member it is bound to. Give a client the key of a member whose group grants exactly the rights that client needs.

## Tips

- Resolve the token to an integer member id only when you can validate it; leave `$idMember` as `null` to fall through.
- Do not set an id for an inactive or banned account — the core check will still reject it.
- Keep the handler fast; it runs on every API request.
