skulich/laravel-clavis

Laravel Clavis is a lightweight token-based authentication middleware package for Laravel APIs

1.1.1 2026-03-31 12:54 UTC

Requires

• php: ^8.3
• laravel/framework: ^12.0 || ^13.0

Requires (Dev)

• larastan/larastan: ^3.8
• laravel/pint: ^1.26
• orchestra/testbench: ^10.8 || ^11.0
• pestphp/pest: ^4.1
• pestphp/pest-plugin-laravel: ^4.0
• pestphp/pest-plugin-type-coverage: ^4.0
• phpstan/extension-installer: ^1.4
• rector/rector: ^2.2
• symfony/var-dumper: ^7.4

MIT

• Siarhei Kulich

• api
• middleware
• auth
• laravel
• token

README

Laravel Clavis is a lightweight token-based authentication middleware package for Laravel APIs.

Perfect for API-first applications and microservices where you need simple and secure token-based authentication without the overhead of Sanctum.

Key benefits:

• 🚀 Quick Setup: Create a token via CLI
• 🔒 Secure: Built on Laravel's native Hash generator
• 🎯 Focused: Designed for server-to-server scenarios
• 🧹 Clean: No migrations, No users, No dependencies

Table of contents

• Installation
• Usage
  • Generate Token
  • Rotate Token
  • API Middleware
• Failed Auth Events
• Nota Bene
• Tests
• Changelog
• Contributing
• License

Installation

Install the package via Composer.

composer require skulich/laravel-clavis

Usage

Generate Token

Generate a new API token via CLI.

The generated token is shown only once. Store it securely and share it over a safe channel.

php artisan clavis:token

Rotate Token

Run the same command to rotate the token. The old token will stop working immediately after regeneration.

php artisan clavis:token

API Middleware

Add the clavis middleware to your API routes.

// Per Route
Route::get('/test', function (Request $request) {
    // return ...
})->middleware('clavis');

// Per Group
Route::middleware('clavis')->group(function () {
    // Route:: ...
});

// Globally in app/bootstrap/app.php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->appendToGroup('api', 'clavis');
})

Failed Auth Events

Failed authentication attempts dispatch Illuminate\Auth\Events\Failed with guard clavis and a masked token.

Event::listen(Failed::class, function (Failed $event) {
    if ($event->guard === 'clavis') {
        Log::warning('Clavis: unauthorized request', $event->credentials);
    }
});

Nota Bene

• CLAVIS_HASH is a secret, treat it like APP_KEY — never commit it to version control.
• For internet-facing endpoints, apply Laravel's throttle middleware alongside clavis to mitigate brute-force attacks.

Tests

Run the entire test suite:

composer test

Changelog

Please see CHANGELOG for more information.

Contributing

Please see CONTRIBUTING for more information.

License

The MIT License (MIT). Please see LICENSE for more information.