Users, roles and permissions in your module

Decide who can see and do what in your module with the platform's roles, and keep a record of who did it.

Copy page for AIUpdated November 9, 2026

Not everyone should approve invoices, and the crew doesn't need to see costs. Your module doesn't build its own user list or login for any of this. It names its permissions, and each workspace hands them out through the roles it already has. One set of people, one set of roles, every module.

Permissions: MODULE.ACTION

Each permission is your module's code, a dot, and an action, such as WORK_ORDERS.APPROVE. Give each one a plain name and a line on who should get it: that's what a Workspace Admin reads when building a role, not the code.

PermissionPlain nameWho it's for
JOBS.VIEWSee jobsEveryone who works jobs
JOBS.EDITAdd and change jobsOffice staff
JOBS.VIEW_COSTSSee costs and marginsManagers only
JOBS.DELETEDelete jobsAdmins

Write each description as what the holder gets to see or do ("See your own crews and their projects"), not "Read access".

Default roles

When a workspace installs your module, its built-in roles get permissions automatically:

  • Admin gets every permission.
  • Operator also gets the view and change ones (VIEW, READ, CREATE, EDIT, USE and similar).
  • Viewer also gets the view ones.
  • Delete, manage and high-risk permissions stay Admin only.

You can override this per permission and name the roles yourself, or none at all. A workspace's own custom roles get nothing until a Workspace Admin adds your permissions to them in System settings › Users and roles.

Checking a permission on a screen and on the server

Check in both places. The screen check keeps things tidy; the server check keeps them safe.

  • On the screen: hide what the person can't use. A button, column or tab they lack the permission for is simply not drawn, never shown and then refused.
  • On the server: every action requires a permission, and data the person may not see is left out of the answer (no cost fields without the cost permission). Hiding something on screen is not security.

Agent tools get this for free: each tool names its permission, and the agent can only do what the person chatting may do. See Agent tools.

Who did it: change logs

The platform tells your module who is acting, so you can keep an honest history:

  • Store a name with every change, such as Recorded by Dana Lee. Most modules keep an activity list on each record: what changed, when, and by whom.
  • Simulated sessions are labelled. When a Workspace Admin uses Simulate to act as someone, the name your module gets reads like Nick Jack: Simulated by Paul Palmer, so the history shows both.
  • Agent tool calls are logged by the platform, along with the full agent session, so you can see what the assistant did and for whom.
  • Need a person's phone or email? Read the workspace's contact details rather than keeping your own copy.

Ask the Module Builder

json
// For developers: module.json
"permissions": [
  {"code": "JOBS.VIEW_COSTS", "label": "See costs and margins",
   "description": "See cost and margin on jobs",
   "help": "For managers. Crews don't need it.",
   "default_roles": ["Admin"]}
]

Good to know

  • Every entry point needs a permission: each screen action, each agent tool, and deleting as its own permission. The module check looks for this. See Publish a module: the module check.
  • Workspace Admins can also open Module Settings for your module, as can anyone holding your module's MANAGE_SETTINGS permission. See Module settings.
  • Outside people (customers, applicants) get a portal role made only of your permissions. See Portals, public pages and signing links.

Can't find what you need? Contact support.