res.forbidden()

This method is used to send a 403 ("Forbidden") response back down to the client indicating that the request is not allowed. This usually means the user-agent tried to do something it was not allowed to do, like change the password of another user.

Usage

return res.forbidden();

Or:

  • return res.forbidden(data);
  • return res.forbidden(data, pathToView);

Details

Like the other built-in custom response modules, the behavior of this method is customizable.

By default, it works as follows:

  • If the request "wants JSON" (e.g. the request originated from AJAX, WebSockets, or a REST client like cURL), Sails will send the provided error data as JSON. If no data is provided a default response body will be sent (the string "Forbidden").
  • If the request does not "want JSON" (e.g. a URL typed into a web browser), Sails will attempt to serve one of your views.
    • If a specific pathToView was provided, Sails will attempt to use that view.
    • Alternatively if pathToView was not provided, Sails will serve a default error page (the view located at views/403.ejs). If that view does not exist, Sails will just send JSON.
    • If Sails serves a view, the data argument will be accessible as a view local: data.

Example

Using the default view:

if ( !req.session.canEditSalesforceLeads ) {
  return res.forbidden('Write access required');
}

With a custom view:

if ( !req.session.canEditSalesforceLeads ) {
  return res.forbidden(
    ''Write access required'',
    'salesforce/leads/edit'
  );
}

Notes

  • This method is terminal, meaning it is generally the last line of code your app should run for a given request (hence the advisory usage of return throughout these docs).
  • res.forbidden() (like other userland response methods) can be overridden or modified. It runs the response method defined in /responses/forbidden.js, which is bundled automatically in newly generated Sails apps. If a forbidden.js response method does not exist in your app, Sails will implicitly use the default behavior.
  • If pathToView refers to a missing view, this method will respond as if the request "wants JSON". +By default, the specified error (err) will be excluded if the app is running in the "production" environment (i.e. process.env.NODE_ENV === 'production').