https://github.com/ryangjchandler/bearer
Minimalistic token-based authorization for Laravel API endpoints.
https://github.com/ryangjchandler/bearer
api api-auth laravel laravel-api
Last synced: 3 months ago
JSON representation
Minimalistic token-based authorization for Laravel API endpoints.
- Host: GitHub
- URL: https://github.com/ryangjchandler/bearer
- Owner: ryangjchandler
- License: mit
- Created: 2021-05-14T12:08:04.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-02T22:57:39.000Z (5 months ago)
- Last Synced: 2025-03-30T21:05:44.892Z (4 months ago)
- Topics: api, api-auth, laravel, laravel-api
- Language: PHP
- Homepage:
- Size: 73.2 KB
- Stars: 81
- Watchers: 2
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# Bearer
[](https://packagist.org/packages/ryangjchandler/bearer)
[](https://github.com/ryangjchandler/bearer/actions?query=workflow%3Arun-tests+branch%3Amain)
[](https://packagist.org/packages/ryangjchandler/bearer)
Minimalistic token-based authorization for Laravel API endpoints.
## Installation
You can install the package via Composer:
```bash
composer require ryangjchandler/bearer
```
You can publish and run the migrations with:
```bash
php artisan vendor:publish --provider="RyanChandler\Bearer\BearerServiceProvider" --tag="bearer-migrations"
php artisan migrate
```
You can publish the config file with:
```bash
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.
```php
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.
```php
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.
```php
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.
```php
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.
```php
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.
```php
$token = Bearer::find('my-token-string');
$token->update([
'expires_at' => now()->addWeek(),
]);
```
Or just use the class's helper methods.
```php
$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.
```php
$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.
```php
$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
```bash
composer test
```
## Contributing
Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
- [Ryan Chandler](https://github.com/ryangjchandler)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.