# 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.

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.

| Permission | Plain name | Who it's for |
|---|---|---|
| `JOBS.VIEW` | See jobs | Everyone who works jobs |
| `JOBS.EDIT` | Add and change jobs | Office staff |
| `JOBS.VIEW_COSTS` | See costs and margins | Managers only |
| `JOBS.DELETE` | Delete jobs | Admins |

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](article:8b4baa95-08a0-4e8e-a7e4-890815c6005b).

> **Workspace Admins hold everything.** Ask the platform "may this person do X?" rather than looking for a code in their list, so admins pass every check.

## 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

> *"Add a See costs permission. Only people with it see the cost and margin columns on jobs, and the server leaves those fields out for everyone else. Keep a history on each job of who changed what."*

```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](article:cfb41dcb-edee-4f32-979c-d0f041eff1f8).
- **Workspace Admins can also open Module Settings** for your module, as can anyone holding your module's MANAGE_SETTINGS permission. See [Module settings](article:549e2ab5-49bd-48b8-8c86-d54d51ba8914).
- **Outside people** (customers, applicants) get a portal role made only of your permissions. See [Portals, public pages and signing links](article:0070604b-7cb0-40eb-bbbb-52b019ff0cb5).


Source: https://datavisions.ai/docs/creators/platform-services/users-roles-and-permissions-in-your-module
