2.0.0-0 • Public • Published


Hook that provides jwt authentication sails-compatible scheme, such as policies, routes, controllers, services. Based on


npm install sails-hook-authorization --save


This hook has support for working with wetland assuming you're using the wetland hook for sails. You can enable this by adding the following in config/auth.js:

module.exports.auth = {
  wetland: true


This hook supports configuration options to make it fit into your application.

module.exports.auth = {

  // Your implementation for sending out the verification email
  sendVerificationEmail: (user, activateToken) => {
    // @todo implement

  // Options concerning a user's identity
  identityOptions: {

    // Property to use for login (one of "email" or "username").
    loginProperty: 'username',

    // Parameters for user sign-up. @see
    parameterBlueprint: ['username', {param: 'email', required: false}],

    // Option to define which relations to populate on the user find
    // can be an array (of relations), a string (single relation), or a boolean (all or nothing).
    populate: true,

    // Whether or not you wish to require a user to validate their email address before being able to log in.
    requireEmailVerification: false

  jwt: {
    // Properties to store on the token. Useful for instance to store the user's role, or language.
    // Accepts nested arguments. E.g.: ['role', {locale: ['language', 'locale']}]
    payloadProperties: [],
    // Time to live for the access token
    accessTokenTtl: 86400,  // 1 day
    // Time to live for the refresh token
    refreshTokenTtl: 2592000, // 30 days
    // The secret used to sign tokens with.
    secret: 'superSecretKeyForJwt'

  // If you're using wetland (requires different query types)
  wetland: true


This module globally expose a service which integrates with the jsonwebtoken ( and provide the interface to apply the jwt specification (

module.exports.validatePassword = function(currentPassword, oldPassword) {
  return Promise.resolve(true);

module.exports.findAccessToken = function(req) {
  return accessToken;

module.exports.issueTokenForUser = function(user) {
  return token;

module.exports.issueToken = function(payload, options) {
  return token

module.exports.verifyToken = function(token) {
  return Promise.resolve(token);

module.exports.decodeToken = function(token, options) {
  return decodedToken;

module.exports.refreshToken = function(decodedToken, expiresIn) {
  return Promise.resolve(token);

module.exports.issueRefreshTokenForUser = function(token) {
  return token;

// renews the `access_token` based on the `refresh_token`
module.exports.validateRefreshToken = function(accessToken, refreshToken) {
  return Promise.resolve(tokens);

// set the token payload issued by login
module.exports.payloadBuilder = function (user, payload) { = 'bar';

  return payload;


It's possible to override payloadBuilder() with your own function. This allows you to extend/populate the token payload with custom data or logic.


You can extend the token payload by giving setting sails.config.auth.jwt.payloadProperties. The user object is used to populate the properties.


  let properties = ['disabled', {groups: 'id'}];

  return {
    user    :,       // default
    username: user.username, // default
    disabled: user.disabled,
    groups  : [3, 4, 6] // get the id's from an array with objects


The verifyToken.js and ensureToken.js policies are just like any other Sails policy and can be applied as such. It's responsible for parsing the token from the incoming request and validating it's state.

Use it as you would use any other sails policy to enable authentication restriction to your Controllers/Actions:

module.exports.policies = {
  'AuthController': ['verifyToken', 'ensureToken'],


This hook sets up a basic User model with some defaults attributes required to implement the jwt authentication scheme such as username, email and emailConfirmed. The User model can be extended with any property you want by defining it in your own Sails project.


These are the routes provided by this hook:

module.exports.routes = {
  'POST /login'                  : 'AuthController.login',
  'POST /signup'                 : 'AuthController.signup',
  'GET /auth/verify-email/:token': 'AuthController.verifyEmail',
  'GET /auth/me'                 : '',
  'POST /auth/refresh-token'     : 'AuthController.refreshToken'

POST /auth/login

The request to this route /auth/login must be sent with these body parameters:

  email   : '', // or username based on the `loginProperty`
  password: 'test123'

The response:

  access_token : 'jwt_access_token',
  refresh_token: 'jwt_refresh_token'

Make sure that you provide the acquired token in every request made to the protected endpoints, as query parameter access_token or as an HTTP request Authorization header Bearer TOKEN_VALUE.

The default TTL of the access_token is 1 day, refresh_token is 30 days. If the access_token is expired you can expect the expired_token error.

POST /auth/signup

The request to this route /signup must be sent with these body parameters:

  username       : 'test',
  email          : '',
  password       : 'test123'

If the email verification feature is disabled, the response will be the same as the /auth/login.

  access_token : 'new jwt access token',
  refresh_token: 'new jwt refresh token'

If it's enabled you will get a 200 as response:

GET /auth/activate/:token

Account Activation

This feature is off by default and to enable it you must override the requireEmailVerification configuration and implement the function sendVerificationEmail:

module.exports.auth = {
  secret                  : process.env.JWT_SECRET || 'superSecretForDev',
  loginProperty           : 'email',
  requireEmailVerification: false,
  sendVerificationEmail   : (user, activateUrl) => {
    sails.log.error('sails-hook-authorization:: An email function must be implemented through `sails.config.auth.sendVerificationEmail` in order to enable the email verification feature. This will receive two parameters (user, activationLink).');

  // seconds to be valid
  ttl: {
    accessToken : process.env.JWT_TOKEN_TTL || 86400,  // 1 day
    refreshToken: process.env.JWT_REFRESH_TOKEN_TTL || 2592000 // 30 days

GET /auth/me

Returns the user, token protected area.

POST /auth/refresh-token

Refreshes the access_token based on the refresh_token. If the refresh_token is expired it will return expired_refresh_token and the user must login through /login

The request:

  access_token : 'jwt access token',
  refresh_token: 'jwt refresh token'

The response:

  access_token : 'new jwt access token',
  refresh_token: 'new jwt refresh token'




Package Sidebar


npm i sails-hook-authorization

Weekly Downloads






Last publish


  • rwoverdijk