Пока приложение живёт в браузере, хватает сессии и 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 отвечает на вопрос «что разрешено этому токену», политика — «что разрешено этому пользователю с этой записью». Для объектов с владельцем нужны обе проверки.
SPA: cookie или токен
Если фронтенд и 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.