README

Minimalistic token-based authorization for Laravel API endpoints.

Installation

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"

Usage

Creating tokens

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, description: 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();
});

Retrieving a Token instance

To retrieve 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');

Using a token in a request

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

Authorization: Bearer my-token-string

Verifying tokens

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);

Token expiration

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.

Limit tokens to a particular domain

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.

Set a token description

You can optionally set a description for the token.

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

$token->update([
    'description' => 'Example description for the token.',
]);

Note: The description field accepts a maximum of 255 characters.

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

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

Credits

• Ryan Chandler
• All Contributors

License

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