{"id":16789631,"url":"https://github.com/ryangjchandler/bearer","last_synced_at":"2025-04-06T22:05:52.494Z","repository":{"id":44546061,"uuid":"367350846","full_name":"ryangjchandler/bearer","owner":"ryangjchandler","description":"Minimalistic token-based authorization for Laravel API endpoints.","archived":false,"fork":false,"pushed_at":"2025-03-02T22:57:39.000Z","size":75,"stargazers_count":81,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-30T21:05:44.892Z","etag":null,"topics":["api","api-auth","laravel","laravel-api"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ryangjchandler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ryangjchandler"}},"created_at":"2021-05-14T12:08:04.000Z","updated_at":"2025-03-02T23:02:18.000Z","dependencies_parsed_at":"2024-10-26T21:13:09.749Z","dependency_job_id":"45a0e7c1-c426-45c8-b5ab-0f87f8e31932","html_url":"https://github.com/ryangjchandler/bearer","commit_stats":{"total_commits":46,"total_committers":4,"mean_commits":11.5,"dds":"0.26086956521739135","last_synced_commit":"6de89d54e60e112ecb6e35f7e482352a7a715633"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":"spatie/package-skeleton-laravel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryangjchandler%2Fbearer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryangjchandler%2Fbearer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryangjchandler%2Fbearer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryangjchandler%2Fbearer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryangjchandler","download_url":"https://codeload.github.com/ryangjchandler/bearer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247557767,"owners_count":20958047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-auth","laravel","laravel-api"],"created_at":"2024-10-13T08:27:52.742Z","updated_at":"2025-04-06T22:05:52.479Z","avatar_url":"https://github.com/ryangjchandler.png","language":"PHP","funding_links":["https://github.com/sponsors/ryangjchandler"],"categories":[],"sub_categories":[],"readme":"# Bearer\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/ryangjchandler/bearer.svg?style=flat-square)](https://packagist.org/packages/ryangjchandler/bearer)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/ryangjchandler/bearer/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/ryangjchandler/bearer/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/ryangjchandler/bearer.svg?style=flat-square)](https://packagist.org/packages/ryangjchandler/bearer)\n\nMinimalistic token-based authorization for Laravel API endpoints.\n\n## Installation\n\nYou can install the package via Composer:\n\n```bash\ncomposer require ryangjchandler/bearer\n```\n\nYou can publish and run the migrations with:\n\n```bash\nphp artisan vendor:publish --provider=\"RyanChandler\\Bearer\\BearerServiceProvider\" --tag=\"bearer-migrations\"\nphp artisan migrate\n```\n\nYou can publish the config file with:\n```bash\nphp artisan vendor:publish --provider=\"RyanChandler\\Bearer\\BearerServiceProvider\" --tag=\"bearer-config\"\n```\n\n## Usage\n\n### Creating tokens\n\nTo create a new token, you can use the `RyanChandler\\Bearer\\Models\\Token` model.\n\n```php\nuse RyanChandler\\Bearer\\Models\\Token;\n\n$token = Token::create([\n    'token' =\u003e Str::random(32),\n]);\n```\n\nAlternatively, you can use the `RyanChandler\\Bearer\\Facades\\Bearer` facade to `generate` a token.\n\n```php\nuse RyanChandler\\Bearer\\Facades\\Bearer;\n\n$token = Bearer::generate(domains: [], expiresAt: null, description: null);\n```\n\nBy 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.\n\n```php\nuse RyanChandler\\Bearer\\Facades\\Bearer;\n\nBearer::generateTokenUsing(static function (): string {\n    return (string) Str::orderedUuid();\n});\n```\n\n### Retrieving a `Token` instance\n\nTo retrieve a `Token` instance from the `token` string, you can use the `RyanChandler\\Bearer\\Facades\\Bearer` facade.\n\n```php\nuse RyanChandler\\Bearer\\Facades\\Bearer;\n\n$token = Bearer::find('my-token-string');\n```\n\n### Using a token in a request\n\nBearer uses the `Authorization` header of a request to retreive the token instance. You should format it like so:\n\n```\nAuthorization: Bearer my-token-string\n```\n\n### Verifying tokens\n\nTo verify a token, add the `RyanChandler\\Bearer\\Http\\Middleware\\VerifyBearerToken` middleware to your API route.\n\n```php\nuse RyanChandler\\Bearer\\Http\\Middleware\\VerifyBearerToken;\n\nRoute::get('/endpoint', MyEndpointController::class)-\u003emiddleware(VerifyBearerToken::class);\n```\n\n### Token expiration\n\nIf you would like a token to expire at a particular time, you can use the `expires_at` column.\n\n```php\n$token = Bearer::find('my-token-string');\n\n$token-\u003eupdate([\n    'expires_at' =\u003e now()-\u003eaddWeek(),\n]);\n```\n\nOr just use the class's helper methods.\n\n```php\n$token = Bearer::find('my-token-string');\n\n$token-\u003eaddWeeks(1)-\u003esave();\n```\n\nIf you try to use the token after this time, it will return an error.\n\n### Limit tokens to a particular domain\n\nToken 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.\n\n```php\n$token = Bearer::find('my-token-string');\n\n$token-\u003eupdate([\n    'domains' =\u003e [\n        'https://laravel.com',\n    ],\n]);\n```\n\nIf you attempt to use this token from any domain other than `https://laravel.com`, it will fail and abort.\n\n\u003e **Note**: domain checks include the scheme so be sure to add both cases for HTTP and HTTPS if needed.\n\n### Set a token description\n\nYou can optionally set a description for the token. \n\n```php\n$token = Bearer::find('my-token-string');\n\n$token-\u003eupdate([\n    'description' =\u003e 'Example description for the token.',\n]);\n```\n\n\u003e **Note**: The description field accepts a maximum of 255 characters.\n\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Ryan Chandler](https://github.com/ryangjchandler)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryangjchandler%2Fbearer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryangjchandler%2Fbearer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryangjchandler%2Fbearer/lists"}