skulich/laravel-clavis

Laravel Clavis

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.
• Rotating APP_KEY does not invalidate CLAVIS_HASH. Tokens are verified with bcrypt (Hash::check), which is independent of APP_KEY, unlike Laravel's Crypt/encrypt().
• 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.