Before we start to allow users to manage their resources and make changes through our API, we need to think about how we can identify our users and restrict them to resources that they own. This is where Authentication and Authorization comes in, allowing us to identify our users and control what they can and cannot do.

In Laravel you have a couple of different options when it comes to Authentication for your API. From Laravel Sanctum, which offers cookie and session based authentication alongside the ability to have API Access Tokens for each user. To Laravel Passport, which is a fully OAuth 2.1 server with all of the bells and whistles. Now this is where the hard part comes in, deciding which package is going to be right for you. You could choose not to use one of these packages, and roll your own, or use an existing 3rd party solution for JWT tokens. However, we will keep it simple here: Sanctum or Passport.

If you know you are going to be building an application that connects to a lot of different systems, in different ways, and you need tight control over this: Passport is 100% what you need. If you are building an API for a couple of integrations, and allowing your users to easily access their data through the API - Sanctum is a lot easier for both you and them to get started.

For this though, we are going to leverage Laravel Sanctum because it has first party support and it pretty much does what JWT would give you but goes a little bit further. That little extra on top of JWT is what actually makes it super useful for your API, until you may need to reach for leveraging OAuth.

With Laravel Sanctum, you can install it into your Laravel API using the following artisan command:

php artisan install:api

This will install Laravel Sanctum, and do a few additional steps to get this set up and ready to use in your Laravel application.

Once you have installed this, we want to make sure that we are protecting all of our API routes using the right middleware.

// routes/api.php

Route::middleware(['auth:sanctum'])->group(static function (): void {
	// Your API Routes can now go in here.
});

At this point, our Authentication has been handled. Sanctum defined all of the routes, form requests, controllers - literally everything. Now the code may not be in the way I would approach it, but it is good enough to get you started - focus on the real problems you are trying to solve with your API!

Now, out of the box Laravel comes with an extremely powerful authorization functionality in the form of "Gates". Sanctum will provide you with a way to control abilities, which is basically permissions, for your API tokens. But sometimes you need a little more control than that and need to work with a user basis not tokens.

Our API is likely to have some level of ownership embedded within it, where an authenticated user may own certain resources - or perhaps the user is part of a team or workspace that has the ownership, either way it will be inherited ownership to the user. So we need to look at how to control the ownership, in a way that isn't going to force us to write loads of custom code. Laravel, as usual, has us covered. Laravel has Gates, which is how we can fine-grain control access to certain parts of the application and control if/how we can do certain actions. This is extended to Eloquent Policies, which are classes that control if/how a user can view/modify an eloquent model - which in our API is a resource. Let's create our first policy using artisan:

php artisan make:policy ServicePolicy

Inside here, we can start defining how we want to control the permissions for users. Laravel will hook this up in the background to our corresponding Eloquent Model, we just need to make sure that we fill them in so that we define our access policies for users.

final readonly class ServicePolicy
{
	public function view(User $user, Service $service): bool
	{
		if ( ! $user->hasVerifiedEmail()) {
			return false;
		}

		return $user->id === $service->user_id;
	}
}

We can start simple, like the above code example. Can a user view this service. We start by checking if the user has a verified email, if they don't they cannot view this resource. It is important to take a step like email verification to stop anyone from creating a quick account and attempting to access data from your API without first verifying their email at a minimum. Then if they have verified their email address, we can check the ownership of the service against the identity of the user making the request. I find it useful to name these methods in line with the action they are trying to perform such as view, create, update, delete, archive, etc etc.

Then within your controller code, you can call these policies using the Gate facade:

Gate::allows('view', $service);

This will return the boolean, allowing you to then handle the success or failure however you see fit. Let's look at a full controller method for this to see it in action.

final class ShowController
{
	public function __invoke(Request $request, Service $service): Response
	{
		if ( ! Gate::allows('view', $service)) {
			throw new UnauthorizedAccessException(
			  message: "You do not have the correct permissions to access this resource.",
			  status: Response::HTTP_FORBIDDEN,
			);
		}

		return new ModelResponse(
			resource: new ServiceResource(
				resource: $service,
			),
		);
	}
}

Just like that, we are protecting our resources from being accessed by people we do not explicitly allow access to. We throw an UnauthorizedAccessException which will bubble up the exception to our Laravel Exception Handler, which is our central place to handle errors and exceptions in our API. This may report it to an error monitoring service, or convert it to a specific API Response. Either way, it isn't logic that needs to live in our controller.