SDK for Node.js

Roles and permissions

Decide what each of your users may do. A role is a name, like support, with the permissions it gives, like orders:refund. You choose both.

How it works

  1. You create roles in a user pool, each with a list of permissions.
  2. You give roles to users (a user can have several).
  3. When a user signs in, their roles and every permission those roles give go into their access token.
  4. Your routes check the token with requirePermission() or requireRole(). No call to the platform: the token says it all.

You can manage roles in the dashboard (User pools, then your pool) or from your code with the SDK, as below.

Create roles

setup-roles.js
const { SecureCloud } = require("@secure-cloud/sdk");

const cloud = new SecureCloud();
const users = cloud.userPool(process.env.SECURE_CLOUD_POOL_ID);

async function main() {
  await users.createRole({
    name: "support",
    description: "Answers customers",
    permissions: ["orders:read", "orders:refund"],
  });
  await users.createRole({
    name: "admin",
    description: "Runs the shop",
    permissions: ["*"],
  });
}

main();

Run it once: node --env-file=.env setup-roles.js. A name that is taken throws CONFLICT.

NameTypeWhat it is
namestringLowercase letters, digits, dots, colons, dashes or underscores. It can't be changed later.
descriptionstring (optional)Who gets the role, for you and your team.
permissionsstring[]Your own words, like orders:refund. orders:* gives everything under orders; * gives everything.

Give roles to users

server.js
// For example when an admin promotes someone in your app.
await users.addRole(userId, "support");

// And to take it back:
await users.removeRole(userId, "support");

Both are safe to repeat. A user can have up to 20 roles, and a pool up to 50.

Protect routes

server.js
const cookie = { cookie: "access_token" };

// Only users whose roles give this permission.
app.post("/orders/:id/refund", users.requirePermission("orders:refund", cookie), async (req, res) => {
  await refundOrder(req.params.id, req.user.id);
  res.json({ refunded: true });
});

// Only users with this role.
app.get("/admin", users.requireRole("admin", cookie), (req, res) => {
  res.send("Welcome, admin");
});

Signed out users get a 401, and signed in users without the permission a 403. Both are JSON answers, and your route never runs.

Check in your own code

Inside a route, req.user has the user's roles and permissions. hasPermission() understands the wildcards for you.

server.js
const { hasPermission } = require("@secure-cloud/sdk");

app.get("/orders/:id", users.requireUser(cookie), async (req, res) => {
  const order = await findOrder(req.params.id);
  const mine = order.customerId === req.user.id;
  if (!mine && !hasPermission(req.user, "orders:read")) {
    return res.status(404).json({ message: "No such order" });
  }
  res.json(order);
});

Manage roles from code

NameTypeWhat it is
listRoles()Role[]Every role in the pool, with how many users have it.
createRole({ name, description, permissions })RoleCreates a role.
getRole(name)RoleOne role.
updateRole(name, { description, permissions })RoleChanges a role; its users get the new permissions in their next token.
deleteRole(name)nothingDeletes a role and takes it from its users.
addRole(userId, role)PoolUserGives a user a role.
removeRole(userId, role)PoolUserTakes a role from a user.
requireRole(role, { cookie })middlewareLets only users with the role through.
requirePermission(permission, { cookie })middlewareLets only users with the permission through.
hasPermission(user, permission)booleanChecks a permission, wildcards included.
NextExpress helpers →