Пока приложение живёт в браузере, хватает сессии и CSRF-токена. Как только появляется мобильный клиент или внешняя интеграция, нужен другой механизм: долгоживущий токен, который клиент присылает в заголовке. В Laravel за это отвечает Sanctum.

Зачем токены, если есть сессии

Сессия привязана к cookie и браузеру. Мобильное приложение cookie не хранит так же надёжно, а сторонний сервис вообще не умеет проходить форму входа. Токен решает обе задачи: его выдают один раз, клиент хранит его у себя и прикладывает к каждому запросу.

Sanctum умеет и то, и другое: cookie-авторизацию для SPA на том же домене и обычные API-токены для всего остального. Это две разные схемы, и путать их не стоит.

Установка

В Laravel 11 и новее достаточно одной команды:

php8.3 artisan install:api
php8.3 artisan migrate

Команда ставит пакет, создаёт таблицу personal_access_tokens и подключает маршруты routes/api.php. В модели User должен быть трейт HasApiTokens.

Выдача токена

Токен создаётся в контроллере входа после проверки пароля:

$token = $request->user()->createToken(
    'iphone',
    ['posts:read'],
    now()->addDays(30)
);

return response()->json([
    'token' => $token->plainTextToken,
]);

В базу попадает только хеш. plainTextToken показывается один раз и больше не восстанавливается: если клиент потерял строку, токен нужно выпустить заново. Не логируйте ответ и не показывайте его в отчётах об ошибках.

Защита маршрутов и abilities

Route::middleware('auth:sanctum')->group(function () {
    Route::get('/posts', [PostController::class, 'index'])
        ->middleware('ability:posts:read');

    Route::post('/posts', [PostController::class, 'store'])
        ->middleware('ability:posts:write');
});

Проверка прав внутри контроллера выглядит так:

if (! $request->user()->tokenCan('posts:write')) {
    abort(403);
}

Это не замена политикам: ability отвечает на вопрос «что разрешено этому токену», политика — «что разрешено этому пользователю с этой записью». Для объектов с владельцем нужны обе проверки.

Если фронтенд и API на одном домене, лучше cookie-режим Sanctum: браузер сам приложит cookie, а CSRF-защита останется. Токен в localStorage доступен любому XSS, поэтому для браузера он хуже.

Для мобильных приложений и серверных интеграций наоборот: токен в защищённом хранилище устройства — нормальный вариант. Выбирайте по клиенту, а не по привычке.

Отзыв и срок жизни

Выход из текущего сеанса:

$request->user()->currentAccessToken()->delete();

Выход со всех устройств — tokens()->delete(). Просроченные токены удаляются командой sanctum:prune-expired, её стоит поставить в планировщик. Если срок не задавать, токен живёт бессрочно — это удобно, но повышает цену утечки.

Типичные ошибки

  • Токен в URL. Он попадёт в логи, историю и реферер. Только заголовок Authorization: Bearer.
  • Один токен на всех. Выпускайте отдельный на устройство или интеграцию, чтобы отзывать точечно.
  • Права «всё сразу». Список abilities позволяет ограничить чтение и запись.
  • Отсутствие лимитов. throttle:api и лимит на попытки входа обязательны.

Если API используется только для чтения, начните с одного ability read. Расширять права проще, чем отзывать слишком широкий токен у всех клиентов.

В тестах не нужно проходить вход по HTTP: Sanctum::actingAs($user, ['posts:read']) подставляет пользователя и нужные abilities. Проверяйте не только разрешённый запрос, но и запрещённый: 403 должен приходить и при нехватке ability, и при попытке тронуть чужой объект.

API без HTTPS бессмысленен: токен уйдёт в открытом виде. CORS настраивайте только для доверенных доменов и не ставьте * вместе с credentials. Заголовок Authorization не должен попадать в логи — в nginx его нет по умолчанию, а в собственном логгере маскируйте значение.

Для мобильного клиента добавьте отдельный endpoint выхода и обработку ответа 401: приложение должно один раз предложить войти заново, а не повторять запрос в цикле. При смене пароля отзывайте все токены, кроме текущего, иначе украденный доступ переживёт смену учётных данных.

Имя токена помогает разобраться в инциденте: iphone-artem понятнее, чем token1. Поле last_used_at показывает, жив ли ещё доступ, а сортировка по нему — какие устройства давно не заходили.

Проверьте сценарий целиком на стенде: вход, запрос с токеном, истечение срока, отзыв и повторный запрос. Если после отзыва токен продолжает работать, значит, где-то включён кэш ответов или используется старая сессия. О правах на объекты — Policy и Gate, о валидации входа — FormRequest.

Коротко

  • auth:sanctum работает и с токенами, и с cookie SPA;
  • токен хранится в базе хешем, plain-строка показывается один раз;
  • abilities ограничивают действие, политики — доступ к объекту;
  • для браузера предпочтительнее cookie, для мобильных — токен;
  • ставьте срок жизни и sanctum:prune-expired в cron.