Download the PHP package givebutter/laravel-keyable without Composer

Laravel Keyable

Laravel Keyable is a package that allows you to add API Keys to any model. This allows you to associate incoming requests with their respective models. You can also use Policies to authorize requests.

Installation

Require the package in your and update your dependencies:

Publish the migration and config files:

Run the migration:

Usage

Add the trait to your model(s):

Add the middleware to the function in your file:

The middleware will authenticate API requests, ensuring they contain an API key that is valid.

Generating API keys

You can generate new API keys by calling the createApiKey() method from the Keyable trait.

When you do so, it returns an instance of NewApiKey, which is a simple class the contains the actual ApiKey instance that was just created, and also contains the plain text api key, which is the one you should use to authenticate requests.

You can also manually create API keys without using the createApiKey from the Keyable trait, in that case, the instance you get back will have a property called plainTextApikey populated with the plain text API key.

Keep in mind plainTextApikey will only be populated immediately after creating the key.

Accessing keyable models in your controllers

The model associated with the key will be attached to the incoming request as :

Now you can use the keyable model to scope your associated API resources, for example:

Keys Without Models

Sometimes you may not want to attach a model to an API key (if you wanted to have administrative access to your API). By default this functionality is turned off:

Making Requests

By default, laravel-keyable uses bearer tokens to authenticate requests. Attach the API key to the header of each request:

You can change where the API key is retrieved from by altering the setting in the keyable.php config file. Supported options are: bearer, header, and parameter.

Need to pass the key as a URL parameter? Set the mode to parameter and the key to the string you'll use in your URL:

Now you can make requests like this:

Authorizing Requests

Laravel offers a great way to perform Authorization on incoming requests using Policies. However, they are limited to authenticated users. We replicate that functionality to let you authorize requests on any incoming model.

To begin, add the AuthorizesKeyableRequests trait to your base Controller.php class:

Next, create the app/Policies/KeyablePolicies folder and create a new policy:

Lastly, register your policies in AuthServiceProvider.php:

In your controller, you can now authorize the request using the policy by calling $this->authorizeKeyable(<ability>, <model>):

Keyable Model Scoping

When using implicit model binding, you may wish to scope the first model such that it must be a child of the keyable model. Consider an example where we have a post resource:

You may instruct the package to apply the scope by invoking the keyableScoped method when defining your route:

The benefits of applying this scope are two-fold. First, models not belonging to the keyable model are caught before the controller. That means you don't have to handle this repeatedly in the controller methods. Second, models that don't belong to the keyable model will trigger a 404 response instead of a 403, keeping information hidden about other users.

You may use this in tandem with Laravel's scoping to ensure the entire heirarchy has a parent-child relationship starting with the keyable model:

Artisan Commands

Generate an API key:

Delete an API key:

Upgrading

Please see UPGRADING for details.

Security

If you discover any security related issues, please email [email protected].

License

Released under the MIT license. See LICENSE for more information.