Laravel Sanctum Authentication Tutorial
Laravel has always been one of those frameworks that makes you feel like you are building something serious without turning every small task into a struggle. It gives you structure, elegance, and a lot of practical tools that help you move quickly without losing control. Authentication is one of the first places where that balance matters, because almost every real application needs users, sessions, permissions, login flows, and secure access to protected data. That is exactly where Laravel Sanctum becomes so useful. It is lightweight, clean, and flexible enough to handle both first-party SPAs and simple API token authentication without dragging in unnecessary complexity. For many projects, it is the sweet spot between “too minimal to be useful” and “too heavy for what I actually need.”
In this tutorial, we will build a solid understanding of Laravel Sanctum from the ground up. We will look at what Sanctum actually does, when to use it, how it differs from other authentication systems, and how to implement it in a real Laravel application. We will cover SPA authentication using cookies and CSRF protection, then move into personal access tokens for API consumers. Along the way, we will write practical code, explain the moving parts in plain English, and highlight the little details that often confuse people the first time they work with Sanctum. By the end, you should not only know how to make it work, but also understand why it works the way it does.
What Laravel Sanctum Is
Laravel Sanctum is an authentication package designed for two main use cases. The first is authenticating single-page applications, mobile apps, or simple front-end clients that belong to the same project and need session-based authentication through cookies. The second is issuing API tokens for users who need to access your application programmatically. That makes Sanctum a very practical choice for modern apps, especially when you want one system that covers both browser-based and token-based authentication in a clean way.
A lot of people think Sanctum is just “API auth,” but that is only half the story. For SPAs, Sanctum uses Laravel’s normal session cookies and CSRF protection, which means the user logs in like a regular web app user. For API tokens, Sanctum gives you personal access tokens that you can create, store, revoke, and check against abilities. This means you do not need to build two completely separate authentication systems just because your app has both a browser UI and an external API.
That flexibility is the real value. You can build a dashboard with React or Vue that talks to Laravel using cookies, and at the same time expose endpoints to third-party tools using token auth. One package, two styles of auth, much less friction.
When Sanctum Is the Right Choice
Sanctum shines when you are building a modern web application and you want authentication that feels straightforward. It is especially good for:
SPAs that live on the same top-level domain or are configured to work with Laravel sessions
Mobile apps that need simple API tokens
Internal tools and dashboards
SaaS platforms with user accounts and token access
Projects that do not need the full complexity of OAuth
If you need a full OAuth2 server with third-party authorization flows, then Passport is the stronger choice. If all you need is authentication for your own app and a few API tokens, Sanctum is usually enough. That distinction matters because many projects overcomplicate auth too early, then spend days fighting an authentication stack they did not really need.
How Sanctum Works Behind the Scenes
Before we jump into code, it helps to understand the mental model. Sanctum supports two different modes.
In the SPA mode, the browser stores a session cookie after login. When the front end makes requests to Laravel, the browser sends the cookie automatically. Laravel checks the session, validates the CSRF token, and treats the request like a normal authenticated web request. This is ideal for first-party front ends that are part of your application.
In the token mode, the user receives a personal access token. That token is usually sent in the Authorization: Bearer ... header. Laravel validates the token against the database, identifies the user, and optionally checks token abilities before allowing access.
This split is one of Sanctum’s strongest ideas. It avoids forcing every application into the same authentication pattern. A browser-based SPA should not be treated exactly like a third-party API client, and Sanctum respects that difference.
Installing Sanctum
Let us start with a fresh Laravel project. If you do not already have one, create it first. Then install Sanctum with Composer:
composer require laravel/sanctum
After installation, publish the Sanctum configuration and migration files:
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
Then run the migrations:
php artisan migrate
This creates the table used to store personal access tokens. Even if you only plan to use SPA authentication at first, the package still prepares the token infrastructure for you, which is convenient later on when you want to add API token access.
Configuring Sanctum
Once Sanctum is installed, you should review its configuration. The main file is usually config/sanctum.php. In many cases, you will not need to change much, but it is good to know where the important settings live.
For SPA authentication, one of the most important concepts is the list of stateful domains. These are the domains that are allowed to use cookie-based authentication with your Laravel backend. In modern Laravel setups, this is often controlled by environment variables and middleware rather than hardcoded changes, but the principle is the same: Laravel must know which front-end origins are trusted for session-based auth.
A typical .env setup might look like this:
APP_URL=http://localhost:8000
FRONTEND_URL=http://localhost:3000
SESSION_DOMAIN=localhost
SANCTUM_STATEFUL_DOMAINS=localhost:3000,localhost,127.0.0.1:3000,127.0.0.1
These values matter because cookie authentication across different ports and subdomains can be tricky. If your React app runs on localhost:3000 and your Laravel API runs on localhost:8000, the browser needs to understand which requests are stateful and which cookies should be sent. Getting this wrong is one of the most common reasons people think Sanctum is broken when the real issue is just domain configuration.
Setting Up Middleware
Sanctum’s SPA authentication relies on the correct middleware stack. In newer Laravel versions, the EnsureFrontendRequestsAreStateful middleware is automatically wired in a way that helps identify requests coming from your first-party front end. You still need to make sure your application is configured properly for session and CSRF handling.
Your config/cors.php file is also important. For example:
return [
'paths' => ['api/*', 'sanctum/csrf-cookie', 'login', 'logout'],
'allowed_methods' => ['*'],
'allowed_origins' => [env('FRONTEND_URL', 'http://localhost:3000')],
'allowed_origins_patterns' => [],
'allowed_headers' => ['*'],
'exposed_headers' => [],
'max_age' => 0,
'supports_credentials' => true,
];
The key line here is supports_credentials => true. Without it, cookies will not be sent properly from the browser to your Laravel backend, and SPA authentication will fail in confusing ways. When people say “Sanctum does not work with React,” the issue is often not Sanctum itself but a mismatch in CORS and credential settings.
You should also check your session configuration:
'same_site' => 'lax',
'domain' => env('SESSION_DOMAIN', null),
Depending on your deployment structure, you may need same_site and domain adjusted carefully. For subdomains, this matters a lot. If the application is on app.example.com and the API is on api.example.com, cookie scope must be set correctly or the browser will silently ignore the session cookie.
Building Authentication Routes
For SPA authentication, you usually rely on the standard Laravel authentication endpoints. If you are using a starter kit such as Breeze or Jetstream, much of this is already in place. But it is useful to know how the flow works.
A login endpoint might look like this:
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Validation\ValidationException;
Route::post('/login', function (Request $request) {
$credentials = $request->validate([
'email' => ['required', 'email'],
'password' => ['required'],
]);
if (! Auth::attempt($credentials, $request->boolean('remember'))) {
throw ValidationException::withMessages([
'email' => __('auth.failed'),
]);
}
$request->session()->regenerate();
return response()->json([
'message' => 'Logged in successfully',
'user' => $request->user(),
]);
});
This is a very normal session-based login flow. The interesting part is that Sanctum does not replace this logic for SPA authentication. Instead, it works with the existing Laravel session system. That is why Sanctum feels natural: it is not forcing you to learn a completely different login model just to support a front end.
A logout endpoint is equally familiar:
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
Route::post('/logout', function (Request $request) {
Auth::logout();
$request->session()->invalidate();
$request->session()->regenerateToken();
return response()->json([
'message' => 'Logged out successfully',
]);
});
Again, this is standard Laravel session logic. Sanctum simply helps the SPA talk to the backend in a secure way.
Getting the CSRF Cookie
This is one of the steps that trips people up the most. Before logging in from a SPA, you typically need to hit the CSRF cookie endpoint. That allows Laravel to send a CSRF token cookie that the browser will use when making state-changing requests.
The endpoint is:
GET /sanctum/csrf-cookie
From the front end, you usually call it before login. For example, with Axios:
import axios from 'axios';
axios.defaults.withCredentials = true;
axios.defaults.baseURL = 'http://localhost:8000';
export async function login(email, password) {
await axios.get('/sanctum/csrf-cookie');
return axios.post('/login', {
email,
password,
});
}
That withCredentials = true line is critical. Without it, the browser may not include cookies, and the authentication flow will fail even though the backend code is correct. The combination of CSRF cookie plus credentials-based requests is the backbone of SPA security in Sanctum.
Protecting Routes with Auth Middleware
Once a user is authenticated, you can protect routes in the usual Laravel way. For SPA or token-based auth, the auth:sanctum middleware is the one you will use most often.
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
return $request->user();
});
This route returns the authenticated user, whether the request is authenticated via session cookies or via a valid personal access token. That is one of the main advantages of Sanctum: the same middleware can handle both modes cleanly.
You can also protect controller routes:
Route::middleware('auth:sanctum')->group(function () {
Route::get('/profile', [ProfileController::class, 'show']);
Route::put('/profile', [ProfileController::class, 'update']);
Route::get('/orders', [OrderController::class, 'index']);
});
This keeps your route files readable and makes it clear which parts of the application require authentication.
Creating API Tokens
Now let us move into the second major use case: personal access tokens. These are perfect when you want to allow users to authenticate from mobile apps, scripts, third-party clients, or any external integration.
To create a token for a user, you can call createToken() on the user model. Make sure your User model uses the HasApiTokens trait:
namespace App\Models;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Sanctum\HasApiTokens;
class User extends Authenticatable
{
use HasApiTokens;
}
Then create a token like this:
$user = User::where('email', $request->email)->firstOrFail();
$token = $user->createToken('mobile-app-token');
return response()->json([
'token' => $token->plainTextToken,
]);
The plainTextToken is shown only once, at creation time. That is important. You should store it securely on the client side, because later you will not be able to retrieve the raw token from the database. Sanctum stores a hashed version in the database for security.
If you want to assign abilities to the token, you can do that too:
$token = $user->createToken('admin-panel-token', ['orders:read', 'orders:write']);
return response()->json([
'token' => $token->plainTextToken,
]);
These abilities let you limit what that token can do. That is helpful when different clients should have different permissions.
Checking Token Abilities
Once a token is issued, you may want to check whether it has permission to do something specific. Sanctum gives you a clean way to do that.
Inside a route or controller, you can inspect the token abilities:
if ($request->user()->tokenCan('orders:write')) {
// Allow write access
}
You can also use this in middleware logic or inside policies when you need finer-grained access control. This becomes especially useful in apps that expose API tokens to multiple kinds of clients with different access levels.
However, in SPA session authentication, tokenCan() will often return true because the authenticated request is backed by the session rather than a specific API token. That is one of those details that is easy to overlook. The idea is that token abilities are most meaningful for personal access tokens, not for session-authenticated browser users.
Logging In from a Front End
A lot of Sanctum tutorials skip the front-end part or only show backend code. But in real life, the front end is where many problems show up. Let us look at a simple example using Axios in a Vue or React app.
import axios from 'axios';
axios.defaults.withCredentials = true;
axios.defaults.baseURL = 'http://localhost:8000';
export async function getUser() {
const response = await axios.get('/api/user');
return response.data;
}
export async function login(email, password) {
await axios.get('/sanctum/csrf-cookie');
const response = await axios.post('/login', { email, password });
return response.data;
}
export async function logout() {
const response = await axios.post('/logout');
return response.data;
}
A realistic flow looks like this: the app loads, it asks the backend for the current user, and if there is no session it shows the login form. After login, the browser stores the cookie, and future requests automatically carry that session. This is beautiful when it is working because the front end does not have to manage tokens manually for SPA mode.
The user experience also feels natural. The user logs in once and the session behaves like a normal web app session, which is exactly what many applications need.
Example Controller for Token Authentication
Let us say you want to support login for mobile or external clients and return a Sanctum token. You can create a controller like this:
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;
class AuthController extends Controller
{
public function login(Request $request)
{
$data = $request->validate([
'email' => ['required', 'email'],
'password' => ['required'],
'device_name' => ['nullable', 'string'],
]);
$user = User::where('email', $data['email'])->first();
if (! $user || ! Hash::check($data['password'], $user->password)) {
throw ValidationException::withMessages([
'email' => ['The provided credentials are incorrect.'],
]);
}
$tokenName = $data['device_name'] ?? 'api-token';
$token = $user->createToken($tokenName, ['*']);
return response()->json([
'token' => $token->plainTextToken,
'token_type' => 'Bearer',
'user' => $user,
]);
}
public function logout(Request $request)
{
$request->user()->currentAccessToken()?->delete();
return response()->json([
'message' => 'Token revoked successfully',
]);
}
}
Then register the routes:
use App\Http\Controllers\Api\AuthController;
use Illuminate\Support\Facades\Route;
Route::post('/login', [AuthController::class, 'login']);
Route::middleware('auth:sanctum')->post('/logout', [AuthController::class, 'logout']);
This gives you a full token-based login flow. It is simple enough for practical use and flexible enough to grow with your application.
Sending the Token from a Client
On the client side, using a Bearer token is straightforward. After login, you store the token and send it on each request.
import axios from 'axios';
const api = axios.create({
baseURL: 'http://localhost:8000/api',
});
api.interceptors.request.use((config) => {
const token = localStorage.getItem('token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
});
export async function fetchProfile() {
const response = await api.get('/user');
return response.data;
}
There is one important caution here. Storing tokens in localStorage is easy, but it is not always the most secure option. For high-security applications, you should think carefully about your client storage strategy and the threat model you are dealing with. The right choice depends on the kind of application you are building, who the users are, and how sensitive the data is.
Revoking Tokens
One of the nice things about Sanctum is that tokens are easy to revoke. That matters because long-lived tokens are only safe if you have a good way to invalidate them when necessary.
To revoke the current token:
$request->user()->currentAccessToken()->delete();
To revoke all of a user’s tokens:
$user->tokens()->delete();
That is useful when a user changes password, reports a lost device, or simply wants to disconnect all sessions. Security is not only about creating tokens; it is also about making sure they can be removed quickly and predictably.
Limiting Access with Policies and Abilities
Sanctum abilities are helpful, but they are not a complete permission system. In a real application, you often combine token abilities with Laravel policies, gates, and roles.
For example, you might have:
if ($request->user()->tokenCan('orders:write') && Gate::allows('update-order', $order)) {
// Allow action
}
This gives you both client-level access control and business-rule access control. The token says what the client is allowed to attempt, while the policy says whether this user may perform the action on this specific resource. That combination is often much cleaner than trying to force all authorization logic into one layer.
Example: Protected Profile Endpoint
Let us build a realistic endpoint that returns the current user profile.
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
Route::middleware('auth:sanctum')->get('/profile', function (Request $request) {
$user = $request->user();
return response()->json([
'id' => $user->id,
'name' => $user->name,
'email' => $user->email,
'created_at' => $user->created_at,
]);
});
From the client side, this endpoint can be called after login. If the user is authenticated via a cookie session, Laravel will identify them automatically. If they are authenticated via token, the Bearer token will be checked instead. That is the beauty of Sanctum’s unified approach.
Example: SPA Login with React
Here is a simple React example that demonstrates the login process:
import { useState } from 'react';
import axios from 'axios';
axios.defaults.withCredentials = true;
axios.defaults.baseURL = 'http://localhost:8000';
function LoginForm() {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const [message, setMessage] = useState('');
const handleSubmit = async (e) => {
e.preventDefault();
try {
await axios.get('/sanctum/csrf-cookie');
await axios.post('/login', { email, password });
const userResponse = await axios.get('/api/user');
setMessage(`Welcome ${userResponse.data.name}`);
} catch (error) {
setMessage('Login failed');
}
};
return (
<form onSubmit={handleSubmit}>
<input
type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
placeholder="Email"
/>
<input
type="password"
value={password}
onChange={(e) => setPassword(e.target.value)}
placeholder="Password"
/>
<button type="submit">Login</button>
<p>{message}</p>
</form>
);
}
export default LoginForm;
This is intentionally simple, but it shows the complete Sanctum SPA flow: CSRF cookie, login request, and authenticated user retrieval. In a real app, you would add better form validation, loading states, error handling, and routing, but the authentication backbone stays the same.
Example: SPA Login with Vue
If you prefer Vue, the pattern is very similar:
<template>
<form @submit.prevent="login">
<input v-model="email" type="email" placeholder="Email" />
<input v-model="password" type="password" placeholder="Password" />
<button type="submit">Login</button>
<p>{{ message }}</p>
</form>
</template>
<script>
import axios from 'axios';
axios.defaults.withCredentials = true;
axios.defaults.baseURL = 'http://localhost:8000';
export default {
data() {
return {
email: '',
password: '',
message: '',
};
},
methods: {
async login() {
try {
await axios.get('/sanctum/csrf-cookie');
await axios.post('/login', {
email: this.email,
password: this.password,
});
const user = await axios.get('/api/user');
this.message = `Welcome ${user.data.name}`;
} catch (error) {
this.message = 'Login failed';
}
},
},
};
</script>
Again, the pattern is almost identical. That is part of why Sanctum is pleasant to work with. It does not force your front end into a strange shape just to satisfy the authentication layer.
Testing Sanctum Authentication
Testing authentication is just as important as building it. In Laravel, feature tests make this straightforward.
Here is a basic test for authenticated API access:
use App\Models\User;
use Laravel\Sanctum\Sanctum;
use Illuminate\Foundation\Testing\RefreshDatabase;
uses(RefreshDatabase::class);
it('returns the authenticated user', function () {
$user = User::factory()->create();
Sanctum::actingAs($user);
$response = $this->getJson('/api/user');
$response->assertOk()
->assertJson([
'id' => $user->id,
'email' => $user->email,
]);
});
And here is a test for token abilities:
it('allows token with proper ability', function () {
$user = User::factory()->create();
Sanctum::actingAs($user, ['orders:write']);
$response = $this->postJson('/api/orders', [
'name' => 'New Order',
]);
$response->assertStatus(201);
});
Tests are where you verify that your auth assumptions are actually true. Authentication code tends to look fine in development until one missing domain config, one wrong middleware, or one forgotten withCredentials setting breaks the whole flow. Good tests help you catch those issues early.
Common Problems and How to Fix Them
One of the most common Sanctum issues is a 419 Page Expired error. This usually points to a CSRF or session problem. It often means the CSRF cookie was not requested properly, the browser did not send credentials, or session settings are mismatched.
Another common issue is CORS failure. If your front end is on a different origin, make sure your CORS settings allow credentials and that the allowed origin is exactly correct. Wildcards and credentials do not mix the way people sometimes expect.
A third common problem is authentication seemingly working in Postman but not in the browser. That usually happens because Postman does not behave like a browser. The browser is much stricter about cookies, SameSite behavior, and CORS. Sanctum SPA auth is browser-based, so browser rules matter a lot.
Another subtle issue is forgetting to call /sanctum/csrf-cookie before login. This is one of those steps that feels unnecessary until you understand why it exists. Laravel uses it to protect against CSRF attacks, and skipping it almost always creates a confusing failure.
A fifth issue is assuming token auth and SPA auth are identical. They are not. Sanctum supports both, but they are separate modes. If you are using cookies and sessions, do not treat the flow like a bearer token flow. If you are using tokens, do not expect session behavior to magically appear.
Security Best Practices
Authentication is not just about getting users logged in. It is about making that process dependable and safe.
Use HTTPS in production. This is not optional if you care about token or session security. Cookies and Bearer tokens should travel over encrypted connections.
Regenerate the session after login. This prevents session fixation attacks and is already part of standard Laravel login flows. Do not skip it.
Keep token abilities narrow. Do not hand out more access than a client needs. A token with * can be convenient during development, but production systems usually benefit from more specific abilities.
Revoke unused tokens. Old tokens become risks over time, especially if users forget they exist.
Use policies for business rules. Sanctum handles authentication, but authorization should still be deliberate and well modeled.
Be careful where you store tokens on the front end. Local storage is simple, but it is not always the safest choice. Evaluate the trade-offs based on your app.
Sanctum Versus Passport
This is a question that comes up constantly, and the answer is simpler than people expect. Use Sanctum when you want a lightweight solution for first-party SPA authentication or simple API tokens. Use Passport when you need a full OAuth2 server and more advanced third-party authorization flows.
Passport is powerful, but it comes with more complexity. Sanctum is smaller and usually easier to implement. If your app is mostly one product with one front end and maybe a few tokens, Sanctum is often the more sensible choice.
That is not a knock against Passport. It just means the tools serve different needs. The best framework feature is not the one with the most options; it is the one that fits the actual job in front of you.
A Practical Full Flow Example
Let us put everything together in a simple real-world flow.
A user visits your SPA, which might be a Vue or React app. The app calls /sanctum/csrf-cookie to prepare the CSRF token. The user submits their email and password. Laravel checks the credentials, logs the user in, regenerates the session, and sends back a successful response. From then on, the browser includes the session cookie automatically. When the SPA calls /api/user, Laravel sees the authenticated session and returns the user profile. If the user logs out, the session is invalidated and the CSRF token is regenerated. If the same user later needs mobile access, you issue them a personal access token, and the mobile app sends it via Authorization: Bearer ....
That is the whole philosophy in one paragraph: session auth for your app’s own front end, token auth for clients that need explicit API credentials, all under one package.
Example User Registration Flow
You often need registration too, so here is a simple example:
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Validator;
Route::post('/register', function (Request $request) {
$data = $request->validate([
'name' => ['required', 'string', 'max:255'],
'email' => ['required', 'email', 'unique:users,email'],
'password' => ['required', 'string', 'min:8', 'confirmed'],
]);
$user = User::create([
'name' => $data['name'],
'email' => $data['email'],
'password' => Hash::make($data['password']),
]);
auth()->login($user);
$request->session()->regenerate();
return response()->json([
'message' => 'Account created successfully',
'user' => $user,
]);
});
This registration flow is simple and effective for SPA apps. After registration, the user is immediately logged in. That is often a better user experience than forcing them through a separate login step after sign-up.
Example of a Token-Based Mobile Endpoint
Suppose your mobile app needs a login endpoint that returns a token. Here is a compact implementation:
Route::post('/api/login', function (Request $request) {
$request->validate([
'email' => ['required', 'email'],
'password' => ['required'],
]);
$user = User::where('email', $request->email)->first();
if (! $user || ! Hash::check($request->password, $user->password)) {
return response()->json([
'message' => 'Invalid credentials',
], 401);
}
$token = $user->createToken('mobile-app', ['profile:read']);
return response()->json([
'token' => $token->plainTextToken,
'user' => $user,
]);
});
Then your app can call protected endpoints like this:
Route::middleware('auth:sanctum')->get('/api/profile', function (Request $request) {
if (! $request->user()->tokenCan('profile:read')) {
return response()->json(['message' => 'Unauthorized'], 403);
}
return response()->json($request->user());
});
This pattern works very well for apps that need a straightforward token system without the overhead of OAuth.
Final Thoughts
Laravel Sanctum is one of those packages that quietly solves a lot of real problems without trying to be everything at once. That is its strength. It understands that modern authentication is not one-size-fits-all. Sometimes you need a session-based SPA login that feels smooth and secure. Sometimes you need a simple personal access token for a mobile app or API client. Sanctum gives you both, and it does so in a way that stays close to the Laravel way of thinking.
The best way to learn Sanctum is not to memorize every config option at once. It is to understand the flow. First, decide whether your client is a browser-based SPA or an external API consumer. Then set up the right cookie, CSRF, and CORS configuration for SPAs, or issue a token for API access. Protect your routes with auth:sanctum. Check abilities where appropriate. Write tests. Revoke tokens when necessary. Keep the setup simple, and Sanctum will feel almost invisible in the best possible way.