Modern applications often use APIs to connect web applications, mobile apps, third-party services, and backend systems.

When an API handles private user information, authentication becomes essential. One popular approach is JWT authentication, which allows an API to securely identify users using JSON Web Tokens.

Laravel provides excellent tools for building APIs, while JWT packages can add token-based authentication to Laravel applications.

In this guide, you’ll learn how to build a Laravel API with JWT authentication, including project setup, API routes, user authentication, token generation, protected routes, middleware, logout, token refresh, validation, security best practices, and common mistakes.

---

What Is JWT Authentication?

JWT, or JSON Web Token, is a compact token format commonly used to authenticate API requests.

Instead of maintaining a traditional server-side session, the client receives a token after successfully logging in.

The client then sends that token with subsequent API requests.

A typical flow looks like this:

┌──────────────┐
│    Client    │
│ Web / Mobile │
└──────┬───────┘
       │
       │ Login
       ▼
┌──────────────┐
│ Laravel API  │
└──────┬───────┘
       │
       │ Verify Credentials
       ▼
┌──────────────┐
│  Database    │
│    User      │
└──────┬───────┘
       │
       │ Generate JWT
       ▼
┌──────────────┐
│ JWT Token    │
└──────┬───────┘
       │
       │ Return Token
       ▼
┌──────────────┐
│    Client    │
└──────────────┘
       │
       │ Authorization: Bearer TOKEN
       ▼
┌──────────────┐
│ Protected API│
└──────────────┘

---

Why Use JWT Authentication in Laravel?

JWT authentication is particularly useful when Laravel is being used as a backend API for:

• React applications
• Vue applications
• Next.js applications
• Mobile applications
• Flutter applications
• Android applications
• iOS applications
• Third-party integrations
• Microservices

JWT can be useful when the frontend and backend are separate applications and the API needs a token-based authentication mechanism.

---

JWT vs Session Authentication

Before implementing JWT authentication, it’s useful to understand how it differs from traditional Laravel session authentication.

Feature	Session Authentication	JWT Authentication
Authentication state	Server-side session	Token-based
Common usage	Traditional web apps	APIs and mobile apps
Client sends	Session cookie	Bearer token
Server session storage	Usually required	Not required for token validation
Mobile API usage	Possible	Common
Stateless API design	Less suitable	Well suited
Token expiration	Session configuration	Token expiration
Scaling	Requires session strategy	Easier for stateless APIs

JWT is not automatically better than sessions. The right choice depends on your application’s architecture.

---

Prerequisites

Before starting, make sure you have:

• PHP installed
• Composer installed
• Laravel installed
• MySQL or another supported database
• Basic Laravel knowledge
• Basic REST API knowledge
• Understanding of authentication concepts

You should also understand HTTP methods such as:

GET
POST
PUT
PATCH
DELETE

---

Step 1: Create a Laravel Project

If you’re starting a new application, create a Laravel project:

composer create-project laravel/laravel laravel-jwt-api

Move into the project:

cd laravel-jwt-api

Start the development server:

php artisan serve

You should now have a Laravel application running locally.

---

Step 2: Configure the Database

Open your .env file:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_jwt
DB_USERNAME=root
DB_PASSWORD=

Update these values according to your database configuration.

Then run:

php artisan migrate

Laravel will create the default database tables, including the users table.

---

Step 3: Install a JWT Package

Laravel itself does not require JWT for API authentication. You need a compatible JWT implementation/package if JWT is the authentication strategy you choose.

A commonly used Laravel JWT package is:

composer require tymon/jwt-auth

After installation, publish its configuration:

php artisan vendor:publish \
    --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"

Then generate the JWT secret:

php artisan jwt:secret

This adds a JWT secret to your environment configuration.

Your .env will contain a value similar to:

JWT_SECRET=your-generated-secret

Never commit your JWT secret to source control.

---

Step 4: Configure the User Model

Open:

app/Models/User.php

Your User model needs to implement the JWT contract.

For example:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Tymon\JWTAuth\Contracts\JWTSubject;

class User extends Authenticatable implements JWTSubject
{
    public function getJWTIdentifier()
    {
        return $this->getKey();
    }

    public function getJWTCustomClaims()
    {
        return [];
    }
}

The two important methods are:

getJWTIdentifier()

and:

getJWTCustomClaims()

The first identifies the authenticated user.

The second allows you to add custom claims when appropriate.

---

Step 5: Configure the Authentication Guard

Open:

config/auth.php

Configure an API guard using the JWT driver.

For example:

'guards' => [

    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'jwt',
        'provider' => 'users',
    ],
],

Make sure your provider points to the correct user model:

'providers' => [

    'users' => [
        'driver' => 'eloquent',
        'model' => App\Models\User::class,
    ],
],

Now Laravel can use the JWT guard for API authentication.

---

Step 6: Create an Authentication Controller

Create a controller:

php artisan make:controller Api/AuthController

Open:

app/Http/Controllers/Api/AuthController.php

You can create login functionality like this:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class AuthController extends Controller
{
    public function login(Request $request)
    {
        $credentials = $request->validate([
            'email' => [
                'required',
                'email',
            ],
            'password' => [
                'required',
            ],
        ]);

        if (!$token = Auth::guard('api')->attempt($credentials)) {
            return response()->json([
                'message' => 'Invalid email or password.'
            ], 401);
        }

        return response()->json([
            'message' => 'Login successful.',
            'token' => $token,
            'token_type' => 'Bearer',
        ]);
    }
}

The authentication process is:

Email + Password
       │
       ▼
 Validate Input
       │
       ▼
Check User Credentials
       │
   ┌───┴────┐
   │        │
Invalid   Valid
   │        │
   ▼        ▼
 401     Generate JWT
            │
            ▼
       Return Token

---

Step 7: Create a Registration API

Authentication usually starts with registration.

Add a registration method:

use App\Models\User;
use Illuminate\Support\Facades\Hash;

Then:

public function register(Request $request)
{
    $validated = $request->validate([
        'name' => [
            'required',
            'string',
            'max:255',
        ],
        'email' => [
            'required',
            'email',
            'max:255',
            'unique:users,email',
        ],
        'password' => [
            'required',
            'string',
            'min:8',
            'confirmed',
        ],
    ]);

    $user = User::create([
        'name' => $validated['name'],
        'email' => $validated['email'],
        'password' => Hash::make(
            $validated['password']
        ),
    ]);

    $token = Auth::guard('api')->login($user);

    return response()->json([
        'message' => 'Registration successful.',
        'user' => $user,
        'token' => $token,
        'token_type' => 'Bearer',
    ], 201);
}

The important security detail is:

Hash::make($validated['password'])

Never store plain-text passwords in your database.

---

Step 8: Add API Routes

Open:

routes/api.php

Add:

use App\Http\Controllers\Api\AuthController;

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

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

Your authentication endpoints are now:

POST /api/register
POST /api/login

---

Step 9: Create a Protected Route

Now create an endpoint that requires authentication.

For example:

Route::middleware('auth:api')->group(function () {

    Route::get(
        '/profile',
        [AuthController::class, 'profile']
    );

});

The middleware verifies the JWT before allowing the request to continue.

The request flow becomes:

Client
  │
  │ Bearer Token
  ▼
auth:api Middleware
  │
  ├── Invalid → 401
  │
  └── Valid
       │
       ▼
   Controller
       │
       ▼
   API Response

---

Step 10: Get the Authenticated User

Add a profile method:

public function profile()
{
    return response()->json([
        'user' => Auth::guard('api')->user()
    ]);
}

Now:

GET /api/profile
Authorization: Bearer YOUR_JWT_TOKEN

can return the authenticated user.

A response might look like:

{
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com"
    }
}

---

Step 11: Implement Logout

JWT-based applications should provide a way to invalidate the current token.

For example:

public function logout()
{
    Auth::guard('api')->logout();

    return response()->json([
        'message' => 'Successfully logged out.'
    ]);
}

Add the route:

Route::middleware('auth:api')->post(
    '/logout',
    [AuthController::class, 'logout']
);

The endpoint becomes:

POST /api/logout

---

Step 12: Implement Token Refresh

JWT authentication often uses short-lived access tokens.

A refresh endpoint can provide a new token when the current token needs to be refreshed, depending on your JWT package configuration and token lifecycle strategy.

For example:

public function refresh()
{
    return response()->json([
        'token' => Auth::guard('api')->refresh(),
        'token_type' => 'Bearer',
    ]);
}

Route:

Route::middleware('auth:api')->post(
    '/refresh',
    [AuthController::class, 'refresh']
);

This gives the client a new token.

---

Complete Authentication Controller

A simple controller can look like this:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Hash;

class AuthController extends Controller
{
    public function register(Request $request)
    {
        $validated = $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users,email',
            'password' => 'required|string|min:8|confirmed',
        ]);

        $user = User::create([
            'name' => $validated['name'],
            'email' => $validated['email'],
            'password' => Hash::make(
                $validated['password']
            ),
        ]);

        $token = Auth::guard('api')->login($user);

        return response()->json([
            'message' => 'Registration successful.',
            'user' => $user,
            'token' => $token,
            'token_type' => 'Bearer',
        ], 201);
    }

    public function login(Request $request)
    {
        $credentials = $request->validate([
            'email' => 'required|email',
            'password' => 'required',
        ]);

        if (!$token = Auth::guard('api')->attempt($credentials)) {
            return response()->json([
                'message' => 'Invalid credentials.'
            ], 401);
        }

        return response()->json([
            'message' => 'Login successful.',
            'token' => $token,
            'token_type' => 'Bearer',
        ]);
    }

    public function profile()
    {
        return response()->json([
            'user' => Auth::guard('api')->user()
        ]);
    }

    public function logout()
    {
        Auth::guard('api')->logout();

        return response()->json([
            'message' => 'Successfully logged out.'
        ]);
    }

    public function refresh()
    {
        return response()->json([
            'token' => Auth::guard('api')->refresh(),
            'token_type' => 'Bearer',
        ]);
    }
}

---

Complete API Routes

Your routes can be organized like this:

use App\Http\Controllers\Api\AuthController;

Route::prefix('auth')->group(function () {

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

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

    Route::middleware('auth:api')->group(function () {

        Route::get(
            '/profile',
            [AuthController::class, 'profile']
        );

        Route::post(
            '/logout',
            [AuthController::class, 'logout']
        );

        Route::post(
            '/refresh',
            [AuthController::class, 'refresh']
        );
    });
});

This creates a clean authentication API structure:

/api/auth/register
/api/auth/login
/api/auth/profile
/api/auth/logout
/api/auth/refresh

---

Testing the Laravel JWT API

You can test the API using tools such as Postman, Insomnia, or another API client.

Register

Send:

POST /api/auth/register
Content-Type: application/json

Body:

{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "password123",
    "password_confirmation": "password123"
}

---

Login

Send:

POST /api/auth/login
Content-Type: application/json

Body:

{
    "email": "john@example.com",
    "password": "password123"
}

A successful response may look like:

{
    "message": "Login successful.",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...",
    "token_type": "Bearer"
}

---

Sending the JWT Token

For protected endpoints, send the token using the HTTP Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

For example:

GET /api/auth/profile
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...

Do not put authentication tokens in URLs.

Avoid:

/api/profile?token=YOUR_TOKEN

Use the Authorization header instead.

---

JWT Authentication Request Flow

The complete authentication architecture looks like this:

┌───────────────┐
│     Client    │
└───────┬───────┘
        │
        │ POST /login
        ▼
┌───────────────┐
│ Laravel API   │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│ Validate User │
│ Credentials   │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│ Generate JWT  │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│ Return Token  │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│     Client    │
└───────┬───────┘
        │
        │ Bearer Token
        ▼
┌───────────────┐
│ JWT Middleware│
└───────┬───────┘
        │
        ▼
┌───────────────┐
│ Protected API │
└───────────────┘

---

Adding JWT Authentication to User Roles

Many applications have multiple user roles.

For example:

User
├── Admin
├── Manager
└── Customer

You can store a role:

role = admin

and use authorization rules to determine what the authenticated user can access.

Authentication answers:

Who is this user?

Authorization answers:

What is this user allowed to do?

These are different concepts and should be implemented separately.

---

Protecting Admin APIs

For example:

Route::middleware('auth:api')
    ->prefix('admin')
    ->group(function () {

        Route::get(
            '/dashboard',
            [AdminController::class, 'dashboard']
        );

    });

You can then add additional authorization logic for admin-only operations.

Do not assume that having a valid JWT automatically means a user is authorized to perform every action.

---

JWT Authentication Security Best Practices

1. Use HTTPS

Always use HTTPS in production.

Avoid sending authentication tokens over plain HTTP.

Use:

https://api.example.com

instead of:

http://api.example.com

---

2. Never Store Plain-Text Passwords

Always hash passwords:

Hash::make($password);

Laravel’s password hashing facilities should be used rather than manually implementing password hashing.

---

3. Protect Your JWT Secret

Your JWT secret is highly sensitive.

Keep it in environment configuration:

JWT_SECRET=your-secret

Never commit it to Git.

---

4. Use Token Expiration

JWT access tokens should not live indefinitely.

Configure an appropriate expiration period based on your application’s security requirements.

Short-lived access tokens can reduce the impact of token exposure.

---

5. Validate API Input

Never trust incoming API data.

For example:

$request->validate([
    'email' => 'required|email',
    'password' => 'required|string',
]);

Validation helps prevent malformed input from reaching business logic.

---

6. Don’t Put Sensitive Data in JWT Claims

JWT payloads can be decoded by clients because JWT encoding is not the same thing as encryption.

Do not put sensitive information such as:

• Passwords
• API secrets
• Credit card information
• Private credentials

inside JWT claims.

---

JWT Authentication vs Laravel Sanctum

Laravel developers often ask whether they should use JWT or Sanctum.

The answer depends on the application’s architecture.

Feature	JWT	Laravel Sanctum
Token-based authentication	Yes	Yes
SPA authentication	Possible	Excellent
Mobile APIs	Excellent	Excellent
Stateless token model	Yes	Supports API tokens
Laravel integration	Package-based	First-party
Token management	JWT-based	Laravel token system
Complexity	Moderate	Generally simpler

For many Laravel applications, Sanctum is worth evaluating before adding a third-party JWT package.

JWT may still be appropriate when your architecture specifically requires JWT-compatible tokens or needs interoperability with external systems that expect JWT.

---

JWT vs OAuth 2.0

JWT and OAuth 2.0 are also frequently confused.

They solve related but different problems.

JWT is a token format.

OAuth 2.0 is an authorization framework.

An OAuth system may use JWTs as tokens, but JWT itself is not an OAuth implementation.

For a straightforward Laravel API where your own frontend or mobile application authenticates directly against your backend, JWT or Sanctum may be sufficient.

For complex third-party delegated authorization, OAuth 2.0 may be more appropriate.

---

Common Laravel JWT Authentication Mistakes

1. Forgetting the API Guard

If the API guard is not configured correctly, authentication attempts may fail.

Check:

'api' => [
    'driver' => 'jwt',
    'provider' => 'users',
],

---

2. Forgetting the JWT Secret

After installing the JWT package, make sure the secret has been generated and configured.

For the commonly used tymon/jwt-auth package:

php artisan jwt:secret

---

3. Not Using the Authorization Header

Protected requests should normally send:

Authorization: Bearer TOKEN

rather than placing tokens in query parameters.

---

4. Returning Too Much User Data

Avoid returning sensitive database columns.

For example, don’t blindly return every database attribute:

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

if your model contains sensitive fields that shouldn’t be exposed.

Instead, explicitly select or transform the response.

---

5. Confusing Authentication With Authorization

A valid JWT proves that the token represents an authenticated identity.

It does not automatically mean the user can access every resource.

Always enforce authorization rules for protected business operations.

---

6. Using Very Long-Lived Tokens

A token that remains valid for an extremely long time increases the potential impact if it is compromised.

Use appropriate expiration and refresh strategies.

---

Recommended Laravel API Structure

As the application grows, avoid putting all authentication logic into one large controller.

A clean structure could look like:

app/
├── Http/
│   ├── Controllers/
│   │   └── Api/
│   │       ├── AuthController.php
│   │       └── UserController.php
│   │
│   ├── Requests/
│   │   ├── LoginRequest.php
│   │   └── RegisterRequest.php
│   │
│   └── Resources/
│       └── UserResource.php
│
├── Models/
│   └── User.php
│
└── Services/
    └── AuthService.php

This makes authentication easier to maintain as the API becomes larger.

---

Using Form Request Validation

Instead of putting all validation inside the controller, you can create a Form Request:

php artisan make:request LoginRequest

Then:

public function rules(): array
{
    return [
        'email' => [
            'required',
            'email',
        ],
        'password' => [
            'required',
            'string',
        ],
    ];
}

Your controller becomes cleaner:

public function login(LoginRequest $request)
{
    $credentials = $request->validated();

    // Authentication logic...
}

This is especially useful for larger APIs.

---

Using API Resources

Laravel API Resources can help control the data returned to clients.

Create one:

php artisan make:resource UserResource

Then:

return new UserResource(
    Auth::guard('api')->user()
);

This gives you more control over the API response and helps prevent accidental exposure of internal model attributes.

---

Example API Response Structure

A consistent API response makes frontend integration easier.

For example:

{
    "success": true,
    "message": "Login successful.",
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...",
        "token_type": "Bearer",
        "user": {
            "id": 1,
            "name": "John Doe",
            "email": "john@example.com"
        }
    }
}

For errors:

{
    "success": false,
    "message": "Invalid credentials."
}

A consistent structure makes APIs easier to consume and debug.

---

Production Checklist

Before deploying a Laravel JWT API to production, verify:

☐ HTTPS is enabled
☐ JWT secret is protected
☐ Passwords are hashed
☐ Login input is validated
☐ Protected routes use authentication middleware
☐ Authorization rules are implemented
☐ Token expiration is configured
☐ Sensitive JWT claims are avoided
☐ Sensitive user fields are hidden
☐ API responses are controlled
☐ Rate limiting is configured
☐ Error responses don't expose secrets
☐ Environment variables aren't committed
☐ Authentication endpoints are tested
☐ Logout and token lifecycle are tested

---

Frequently Asked Questions

1. How do I build a Laravel API with JWT authentication?

Install a compatible JWT package, configure the API authentication guard, update the User model, create authentication endpoints, generate JWT tokens during login, and protect API routes with authentication middleware.

---

2. What is JWT authentication in Laravel?

JWT authentication allows a Laravel API to authenticate users using JSON Web Tokens. After login, the API returns a token that the client sends with subsequent protected requests.

---

3. How do I generate a JWT token in Laravel?

With a JWT package such as tymon/jwt-auth, you can authenticate credentials through the configured JWT guard:

$token = Auth::guard('api')->attempt($credentials);

The generated token can then be returned to the client.

---

4. How do I protect Laravel API routes with JWT?

Apply the configured authentication middleware to the route:

Route::middleware('auth:api')->group(function () {
    Route::get('/profile', [
        AuthController::class,
        'profile'
    ]);
});

The middleware checks the authentication token before allowing access.

---

5. Is JWT better than Laravel Sanctum?

Not necessarily.

Sanctum is a first-party Laravel authentication solution and is often simpler for Laravel applications. JWT can be useful when the application specifically requires JWT tokens or needs JWT interoperability with other systems.

---

6. Where should I store a JWT token?

The appropriate storage strategy depends on the client application and its threat model.

For browser applications, carefully evaluate the security implications of local storage, cookies, CSRF protection, XSS, and token exposure. For mobile applications, use the platform’s secure credential storage mechanisms where appropriate.

Never expose tokens unnecessarily or include them in URLs.

---

7. Can JWT authentication be used with mobile applications?

Yes. JWT-based APIs can be used by mobile applications such as Flutter, Android, and iOS clients.

The mobile application authenticates with the Laravel API, receives a token, and sends that token with subsequent protected requests.

---

8. How do I refresh a JWT token in Laravel?

If your JWT implementation supports token refreshing, you can expose a refresh endpoint and generate a new token according to your configured token lifecycle.

For example:

$token = Auth::guard('api')->refresh();

The exact refresh strategy should be designed around your security requirements and the JWT package version you use.

---