Skip to main content

Authorization

Once a caller is authenticated, the next question is what they're actually allowed to do. RapidREST's authorization system is a Roles Based Access Control system, and the cheapest, most common layer of it is a plain role check on the endpoint itself, before anything touches a database. Reach for Access Control Lists instead when a role check isn't precise enough, permission that depends on which specific record is being touched, not just who's asking.

@RequiresRole​

The simplest form of authorization: require the authenticated user to have one of the given roles.

@RequiresRole('admin')
@Delete('/:id')
async deletePet(@Param('id') id: string) {
  return this.petService.delete(id);
}

A request from a user without a matching role is rejected before the handler ever runs, 403, the same error response shape as any other ApiError.

@RequiresScope (route-level)​

A coarser, token-level check, distinct from ACLs: require the authenticated user's JWT to carry one or more scopes before the handler runs at all. This is checked before any per-resource ACL check, so it's a cheap way to reject requests from tokens that were never issued the right scope, without touching the database at all:

@RequiresScope('pets:write')
@Delete('/:id')
async deletePet(@Param('id') id: string) {
  return this.petService.delete(id);
}

Scopes live on JWTUser.scopes, set by whatever issued the token (for example, @rapidrest/auth's User.scopes, built at runtime rather than stored). ACLAction.FULL ("*") also satisfies any required scope.

This is unrelated to the property-level @RequiresScope documented in Models & Persistence, which hides individual fields from a response rather than gating an entire endpoint, same name, different job, different layer entirely.

Two more guard decorators​

Beyond a plain role or scope, two further checks gate a handler the same way: @RequiresElevation requires a recently confirmed elevated session, a re-authentication step, before letting a sensitive action through, and @RequiresTrustedRole requires one of the roles listed in trusted_roles specifically. Both run as part of the same request pipeline @RequiresRole and @RequiresScope do, see Lifecycle & Validation for exactly where each one sits relative to the others.

trusted_roles is its own thing

@RequiresTrustedRole checks against trusted_roles explicitly. @RequiresRole doesn't, it only ever checks the exact role list you passed it, so holding a trusted role does not automatically satisfy an unrelated @RequiresRole('editor') check. trusted_roles has a separate bypass effect inside the ACL system, the two mechanisms don't call into each other.