Role-Based API Access in Laravel 12 with Sanctum: A Beginner’s Guide

🤔 “Why Can the Intern Access the Admin Panel?!”

Imagine you’ve just finished building an API for your shiny new Laravel 12 app. You’ve got login working, data is flowing... but wait.

Suddenly, your intern logs in and deletes all the user data—because your API doesn’t know the difference between an admin, a manager, or a user.

Ouch.

Enter: Role-Based Access Control (RBAC) with Laravel Sanctum.

In this guide, we’ll walk you through how to build secure, role-specific API access using Laravel 12 and Sanctum. Whether you're working on a personal project or building a real-world application, this tutorial will help you create permission-aware APIs without pulling your hair out.

🧱 What You'll Learn

What is Laravel Sanctum?
What is Role-Based Access Control?
Step-by-step: Setting up Sanctum
Creating roles and protecting routes
Middleware & gates for fine-tuned access
Real-life examples

🚪 What is Laravel Sanctum?

Laravel Sanctum is a simple package that allows you to authenticate users via API tokens (SPA or mobile apps). It’s lightweight, easy to implement, and perfect for most Laravel apps.

Unlike Passport, which is OAuth2-heavy, Sanctum keeps it simple—making it beginner-friendly and lightning-fast to set up.

👑 What is Role-Based Access Control (RBAC)?

RBAC means giving users different roles, and limiting what each role can do.

Think of it like access badges at a company:

🟢 Admin: Access to everything
🟡 Manager: Limited access
🔵 User: Basic access only

With RBAC, your API checks who’s calling and what they’re allowed to do before serving data.

🚧 Step-by-Step: Setting Up Sanctum and RBAC

Let’s build a simple API where users can log in and get different data based on their roles.

✅ Step 1: Install Sanctum

Install Laravel Sanctum via Composer:

composer require laravel/sanctum

Publish the Sanctum config and run migrations:

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

In your User.php model, add the HasApiTokens trait:

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

✅ Step 2: Add a Role Column to Users Table

Let’s give each user a role.

php artisan make:migration add_role_to_users_table

In the migration file:

public function up()
{
    Schema::table('users', function (Blueprint $table) {
        $table->string('role')->default('user');
    });
}

Then run:

php artisan migrate

Now, users can have roles like admin, manager, or user.

✅ Step 3: Register & Login Users with Tokens

Let’s create an auth controller for register and login.

php artisan make:controller AuthController

In AuthController.php:

public function register(Request $request)
{
    $user = User::create([
        'name' => $request->name,
        'email' => $request->email,
        'password' => bcrypt($request->password),
        'role' => $request->role ?? 'user',
    ]);

    $token = $user->createToken('api-token')->plainTextToken;

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

public function login(Request $request)
{
    $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('api-token')->plainTextToken;

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

✅ Step 4: Create a Middleware to Check Role

php artisan make:middleware RoleMiddleware

In app/Http/Middleware/RoleMiddleware.php:

public function handle($request, Closure $next, $role)
{
    if ($request->user()->role !== $role) {
        return response()->json(['message' => 'Unauthorized'], 403);
    }

    return $next($request);
}

->withMiddleware(function ($middleware) {
    $middleware->alias([
        'role' => \App\Http\Middleware\RoleMiddleware::class,
    ]);
})

✅ Step 5: Protect API Routes Based on Role

In routes/api.php:

// Public route
Route::post('/register', [AuthController::class, 'register']);
Route::post('/login', [AuthController::class, 'login']);

// Protected route for admins
Route::middleware(['auth:sanctum', 'role:admin'])->get('/admin', function () {
    return response()->json(['message' => 'Welcome, Admin!']);
});

// Protected route for managers
Route::middleware(['auth:sanctum', 'role:manager'])->get('/manager', function () {
    return response()->json(['message' => 'Manager dashboard']);
});

// For all authenticated users
Route::middleware(['auth:sanctum'])->get('/profile', function (Request $request) {
    return $request->user();
});

🔥 Now, if a user with the user role tries to access /admin, they’ll get blocked with a 403 Forbidden.

🧠 Real-Life Example: E-commerce API

Imagine an e-commerce app:

👤 Users can view products
🛍️ Managers can update inventory
👑 Admins can delete users

Using Sanctum and middleware, you can enforce this easily. That means no more “oops” moments where the wrong user accesses sensitive endpoints.

⚠️ Common Pitfalls (and How to Avoid Them)

🟡 Forgetting to protect routes: Always use middleware on your sensitive routes.

🔐 Not hashing passwords: Use bcrypt() when registering users.

❌ Hardcoding roles: You can improve this by moving to a roles table and many-to-many relationships later.

💡 Bonus Tips

Use Laravel Gates/Policies for fine-grained permissions
Store roles in a config file or DB for more flexibility
Create a hasRole() helper in the User model for cleaner code

public function hasRole($role)
{
    return $this->role === $role;
}

Recap: What You Learned

By now, you should be able to:

Set up Laravel Sanctum for API authentication
Add roles to users
Use custom middleware to control access
Protect your API from unauthorized access

🧪 Next Steps

Try building a simple blog API with:

Users (read only)
Editors (create/edit posts)
Admins (delete anything)

Use the same pattern you learned today—and watch your Laravel skills level up 🚀

💬 FAQs

1. Can a user have multiple roles?

Not with this basic setup. But you can extend it using a roles table and many-to-many relationships.

2. Is Sanctum better than Passport?

For simple token-based APIs—yes. Sanctum is easier and lighter.

3. Can I use Sanctum in production?

Absolutely! Just make sure to secure your tokens, use HTTPS, and follow best practices.

💬 Over to You!

Which part of role-based access did you find most useful or confusing?
Drop your questions and thoughts in the comments below—I’m here to help! 👇