PHPackages                             huseynvsal/jwt-auth-refresh - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. huseynvsal/jwt-auth-refresh

ActiveLibrary[Authentication & Authorization](/categories/authentication)

huseynvsal/jwt-auth-refresh
===========================

A Laravel package for JWT authentication with access and refresh tokens.

1.0.2(1y ago)353MITPHPPHP >=8.0

Since Feb 11Pushed 1y ago1 watchersCompare

[ Source](https://github.com/huseynvsal/jwt-auth-refresh)[ Packagist](https://packagist.org/packages/huseynvsal/jwt-auth-refresh)[ RSS](/packages/huseynvsal-jwt-auth-refresh/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (6)Versions (4)Used By (0)

JWT Auth Refresh Package
========================

[](#jwt-auth-refresh-package)

This Laravel package provides JWT authentication with access and refresh token functionality. It includes all the necessary logic for token generation, token refresh, and user logout without the need to write any complex controller or middleware.

Features
--------

[](#features)

- **JWT Access and Refresh Tokens**: Generate access and refresh tokens during login.
- **Token Refresh**: Refresh tokens if the refresh token is valid.
- **Logout**: Remove all refresh tokens during logout.
- **Custom Guards**: Automatically registers a custom JWT guard.
- **Configuration**: Easily configure token expiration times and secret keys.

Installation
------------

[](#installation)

### Step 1: Install the Package

[](#step-1-install-the-package)

Install the package using Composer.

```
composer require huseynvsal/jwt-auth-refresh
```

### Step 2: Publish Resources

[](#step-2-publish-resources)

After installing the package, you need to publish the configuration and migration files.

Run the following command to publish the resources:

```
php artisan vendor:publish --tag=jwt-auth-config
php artisan vendor:publish --tag=jwt-auth-migrations
```

This will publish:

- `config/jwt-auth.php` – The configuration file for JWT tokens (secret keys and expiration times).
- A migration file to create `refresh_tokens` tables.

### Step 3: Run Migrations

[](#step-3-run-migrations)

Run the migration to create the necessary table for storing refresh tokens.

```
php artisan migrate
```

### Step 4: Configure `.env` File

[](#step-4-configure-env-file)

In your .env file, add the following configuration for JWT tokens:

```
JWT_SECRET_KEY=your-secret-key-here
JWT_REFRESH_SECRET_KEY=your-refresh-secret-key-here
JWT_ACCESS_TOKEN_EXPIRATION=3600  # 1 hour
JWT_REFRESH_TOKEN_EXPIRATION=604800  # 7 days
```

- `JWT_SECRET_KEY`: The secret key used to sign JWT tokens. Ensure you keep it secure.
- `JWT_SECRET_KEY`: The secret key used to sign refresh tokens. Ensure you keep it secure.
- `JWT_ACCESS_TOKEN_EXPIRATION`: The expiration time for access tokens (in seconds).
- `JWT_REFRESH_TOKEN_EXPIRATION`: The expiration time for refresh tokens (in seconds).

### Step 5: Set Guard in `config/auth.php`

[](#step-5-set-guard-in-configauthphp)

Your package will automatically register the custom jwt guard for authentication. The next step is to set it in the config/auth.php file.

Ensure that your config/auth.php is configured to use the jwt guard for API authentication.

```
// config/auth.php

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

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

This sets the default guard for API requests to use the custom jwt guard provided by the package.

### Step 6: Update User Model (Optional)

[](#step-6-update-user-model-optional)

If you want to use the JWT-based authentication with your own `User` model, ensure that your User model implements `Illuminate\Contracts\Auth\Authenticatable` and have `refreshTokens` relation defined:

Example:

```
// app/Models/User.php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Huseynvsal\JwtAuthRefresh\Models\AccessToken;
use Huseynvsal\JwtAuthRefresh\Models\RefreshToken;

class User extends Authenticatable
{
    use HasFactory, Notifiable;

    public function refreshTokens(): HasMany
    {
        return $this->hasMany(RefreshToken::class, 'user_id');
    }

    // Additional user logic...
}
```

This is required so that Laravel can authenticate the user using the JWT guard.

---

Usage
-----

[](#usage)

### Step 1: Login and Generate Tokens

[](#step-1-login-and-generate-tokens)

In your `AuthController`, you can use the `JwtAuthService` to generate both the access and refresh tokens when the user logs in.

Example login method:

```
// app/Http/Controllers/AuthController.php

namespace App\Http\Controllers;

use App\Models\Customer;
use Huseynvsal\JwtAuthRefresh\Exceptions\InvalidTokenException;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Huseynvsal\JwtAuthRefresh\Services\JwtAuthService;

class AuthController extends Controller
{
    protected JwtAuthService $jwtAuthService;

    public function __construct(JwtAuthService $jwtAuthService)
    {
        $this->jwtAuthService = $jwtAuthService;
    }

    public function login(): JsonResponse
    {
        $user = User::find(1);

        $accessToken = $this->jwtAuthService->generateAccessToken($user);
        $refreshToken = $this->jwtAuthService->generateRefreshToken($user);

        return response()->json([
            'accessToken' => $accessToken,
            'refreshToken' => $refreshToken
        ]);
    }
}
```

### Step 2: Refresh Tokens

[](#step-2-refresh-tokens)

You can create an API to allow users to refresh their tokens using a valid refresh token.

Example refresh method:

```
// app/Http/Controllers/AuthController.php

public function refresh(Request $request): JsonResponse
{
    try
    {
        $tokens = $this->jwtAuthService->refreshTokens($request->input('refreshToken'));

        return response()->json($tokens);
    }
    catch (InvalidTokenException $e)
    {
        return response()->json(['error' => $e->getMessage()], 401);
    }
}
```

### Step 3: Logout and Revoke Tokens

[](#step-3-logout-and-revoke-tokens)

To handle logout, you can delete the user's access and refresh tokens:

```
// app/Http/Controllers/AuthController.php

public function logout(): JsonResponse
{
    $user = auth()->user();
    $this->jwtAuthService->revokeTokensForUser($user);

    return response()->json(['message' => 'Logged out successfully']);
}
```

---

Additional Information
----------------------

[](#additional-information)

- **JWT Tokens:** The refresh tokens will be stored in the refresh\_tokens tables.
- **Guard Usage:** The jwt guard is automatically registered, and you can use the auth() helper to authenticate users using JWT tokens in your controllers.
- **Expiration:** Both access and refresh tokens have configurable expiration times defined in the config/jwt-auth.php file.

###  Health Score

28

—

LowBetter than 52% of packages

Maintenance41

Moderate activity, may be stable

Popularity12

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Total

3

Last Release

493d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/61144551?v=4)[Vüsal](/maintainers/huseynvsal)[@huseynvsal](https://github.com/huseynvsal)

---

Top Contributors

[![huseynvsal](https://avatars.githubusercontent.com/u/61144551?v=4)](https://github.com/huseynvsal "huseynvsal (6 commits)")

### Embed Badge

![Health badge](/badges/huseynvsal-jwt-auth-refresh/health.svg)

```
[![Health](https://phpackages.com/badges/huseynvsal-jwt-auth-refresh/health.svg)](https://phpackages.com/packages/huseynvsal-jwt-auth-refresh)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[spatie/laravel-permission

Permission handling for Laravel 12 and up

12.9k102.4M1.4k](/packages/spatie-laravel-permission)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M132](/packages/laravel-pulse)[laravel/passport

Laravel Passport provides OAuth2 server support to Laravel.

3.5k91.9M595](/packages/laravel-passport)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[api-platform/laravel

API Platform support for Laravel

58171.6k14](/packages/api-platform-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)