Minimalistic token-based authorization for Laravel API endpoints.

You can install the package via Composer:

composer require ryangjchandler/bearer

You can publish and run the migrations with:

php artisan vendor:publish --provider="RyanChandler\Bearer\BearerServiceProvider" --tag="bearer-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --provider="RyanChandler\Bearer\BearerServiceProvider" --tag="bearer-config"

To create a new token, you can use the RyanChandler\Bearer\Models\Token model.

use RyanChandler\Bearer\Models\Token;

$token = Token::create([
    'token' => Str::random(32),
]);

Alternatively, you can use the RyanChandler\Bearer\Facades\Bearer facade to generate a token.

use RyanChandler\Bearer\Facades\Bearer;

$token = Bearer::generate(domains: [], expiresAt: null);

By default, Bearer uses time-ordered UUIDs for token strings. You can modify this behaviour by passing a Closure to Bearer::generateTokenUsing. This function must return a string for storage to the database.

use RyanChandler\Bearer\Facades\Bearer;

Bearer::generateTokenUsing(static function (): string {
    return (string) Str::orderedUuid();
});

To retreive a Token instance from the token string, you can use the RyanChandler\Bearer\Facades\Bearer facade.

use RyanChandler\Bearer\Facades\Bearer;

$token = Bearer::find('my-token-string');

Bearer uses the Authorization header of a request to retreive the token instance. You should format it like so:

Authorization: Bearer my-token-string

To verify a token, add the RyanChandler\Bearer\Http\Middleware\VerifyBearerToken middleware to your API route.

use RyanChandler\Bearer\Http\Middleware\VerifyBearerToken;

Route::get('/endpoint', MyEndpointController::class)->middleware(VerifyBearerToken::class);

If you would like a token to expire at a particular time, you can use the expires_at column.

$token = Bearer::find('my-token-string');

$token->update([
    'expires_at' => now()->addWeek(),
]);

Or just use the class's helper methods.

$token = Bearer::find('my-token-string');

$token->addWeeks(1)->save();

If you try to use the token after this time, it will return an error.

Token usage can be restricted to a particular domain. Bearer uses the scheme and host from the request to determine if the token is valid or not.

$token = Bearer::find('my-token-string');

$token->update([
    'domains' => [
        'https://laravel.com',
    ],
]);

If you attempt to use this token from any domain other than https://laravel.com, it will fail and abort.

Note: domain checks include the scheme so be sure to add both cases for HTTP and HTTPS if needed.

composer test

Please see CONTRIBUTING for details.

Please review our security policy on how to report security vulnerabilities.

• Ryan Chandler
• All Contributors

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