Welcome back! In the last lesson, you learned how to protect your API routes so that only authenticated users with a valid JWT can access them. That’s a great start, but in most real-world applications, not all users should have the same permissions. For example, you might want only administrators to be able to delete books or update user information, while regular users can only view data.

In the previous unit we only had JwtAuthGuard: any authenticated user could perform mutations (create/update/delete). That’s intentionally incomplete. In this unit we’ll require roles for sensitive actions. To make this concrete now, we’ll use an admin role (you already have a seeded admin user). In the SPA playground provided with the course you can try both a normal user and an admin; later, in the frontend path, you’ll build your own React UI.

This is where role-based authorization comes in. With role-based authorization, you can control what actions different types of users can perform in your API. In this lesson, you’ll learn how to implement this in your NestJS project so you can restrict certain endpoints to users with specific roles, like admin or user.

Before we dive in, let’s quickly remind ourselves of the current setup. You already have:

• Registration (bcrypt hashes stored).
• JWT Login (token with sub, role, iat, exp).
• JwtAuthGuard (only checks if the token is valid → user is logged in).

Here’s a simplified code block to show where we are, focusing on how user roles fit in:

What’s wrong

• Any logged-in user can call write endpoints (e.g., create a book). That violates least-privilege.

What we’ll add

• @Roles() decorator to declare required roles on a route.
• RolesGuard to enforce those requirements after JwtAuthGuard authenticates the user.
• BooksController write routes become admin-only (read routes remain public or authenticated as you decide).

In NestJS, a decorator is a special function you can use to add extra behavior to classes or methods. We’ll create a custom @Roles() decorator to mark which endpoints require certain roles.

Here’s how you can define it:

Explanation:

• SetMetadata is a NestJS helper that attaches custom metadata to a route handler or controller.
• ROLES_KEY is the key we’ll use to store the roles.
• Role is a TypeScript type for allowed roles.
• Roles(...roles) is the decorator you’ll use on your endpoints, like @Roles('admin').

What is metadata here?

In Nest, metadata is just key–value data attached to a class or handler at design time. Decorators like @Get() and @Post() also attach metadata. Nest provides the Reflector to read that metadata later (inside guards, interceptors, etc.).

Why SetMetadata?

SetMetadata(ROLES_KEY, roles) writes onto the route handler. The guard will read this value and decide access. This avoids hard-coding roles inside the guard; routes declare their own policy, the guard enforces it.

A guard in NestJS is a class that decides whether a request should be handled or rejected. We’ll create a RolesGuard that checks if the user’s role matches the required roles for an endpoint.

Here’s the code for the guard:

Explanation:

• Reflector is used to read the metadata set by the @Roles() decorator.
• canActivate is called before the route handler runs.
• It checks if the endpoint has required roles. If not, it allows access.
• It then checks the user’s role (from req.user.role).
• If the user’s role is not in the required roles, it throws a ForbiddenException.
• If the role matches, the request is allowed.

What happens if a user without the right role tries to access an endpoint?

They will get a response like:

Now, let’s see how to use the @Roles() decorator and RolesGuard in your controllers. You’ll combine them with the JwtAuthGuard to make sure only authenticated users with the right role can access certain endpoints.

Here’s an example from the Books controller:

Explanation:

• @UseGuards(JwtAuthGuard, RolesGuard) applies both guards to the endpoint.
• @Roles('admin') marks this endpoint as admin-only.

Admin creates a book (expect 201):

Regular user tries the same (expect 403):

Public/less restricted read:

In this lesson, you learned how to add role-based authorization to your NestJS API. You created a custom @Roles() decorator to mark which endpoints require certain roles and a RolesGuard to enforce these rules. You also saw how to apply these tools in your controllers to restrict actions like creating or deleting books to admins only.

Key outcomes to verify in your environment:

• Write endpoints (POST/PATCH/DELETE /books) return 403 for a regular user and 2xx for an admin.
• Read endpoints remain reachable as designed (public or auth-only).
• Swapping guard order to @UseGuards(RolesGuard, JwtAuthGuard) fails correctly because req.user won’t exist—this confirms you understand the dependency between guards.

Role-based authorization is a key part of building secure and flexible APIs. It lets you control exactly who can do what in your application.

Next, you’ll get a chance to practice these concepts yourself. You’ll write and test endpoints with role-based restrictions, so you can be confident in securing your own APIs. Great work getting this far — let’s keep going!