# Roles, Permissions & User Access

This guide explains how access control works in NexWave: how roles, role profiles, and user permissions fit together, and how to configure them so each member of your team has exactly the access they need (and no more).

If you only have a moment, jump straight to:

* [NexWave Role Catalogue](NexWave-Role-Catalogue.md): plain-English description of every role, plus recommended role bundles by job function.
* [User Permissions and Record-Level Access](User-Permissions-and-Record-Level-Access.md): how to restrict a user to a specific company, branch, warehouse or territory.

## How NexWave Controls Access

NexWave layers four concepts to decide what each user can see and do:

| Layer | What it controls | Example |
|-------|------------------|---------|
| **User** | Who can log in.  | `john@acme.co.nz` |
| **Role** | Which features and document types the user can use. | `Accounts User` lets the user create Sales Invoices. |
| **Role Profile** | A reusable bundle of roles assigned in one click. | A `Bookkeeper` profile that bundles `Accounts User` plus `Employee`. |
| **User Permission** | Restricts the user to specific records within those documents. | John can only see Sales Invoices for `ACME NZ Ltd`, not the Australian company. |

A simple way to remember it: **Roles say *what* a user can do. User Permissions say *which records* they can do it on.**

A fifth, advanced concept (Permission Levels) lets you hide individual fields, such as cost prices on a Sales Order. It is only used in specialised setups; see [Role Permissions Manager](Role-Permissions-Manager.md) when you need it.

## Before You Start

A few decisions to make up front save a lot of clean-up later:

* **Per-person or shared profile?** If three or more users share the same job, build a Role Profile rather than assigning roles individually. It keeps onboarding consistent and makes future adjustments easier.
* **Who needs System Manager?** Almost no-one. System Manager is the highest level of access in NexWave: it can change settings, edit any record, and remove other users. Limit it to one or two people and require Two-Factor Authentication on those accounts.
* **Audit before you add.** Before onboarding a new staff member, run the User List and review who already has elevated access. It is easy to forget to revoke roles when staff change positions.

## Roles

A Role is a named bundle of permissions over specific document types. NexWave ships with the standard set used across most businesses (System Manager, Accounts User, Sales User, Stock User and so on), plus a small number of NexWave-specific roles such as `NexWave AI User`.

* **System-shipped roles** are maintained by NexWave and updated with each release. Use these wherever possible.
* **Custom roles** can be created if you genuinely need access patterns that the shipped roles do not cover. Avoid creating roles for one-off situations: a tangle of one-person roles becomes very hard to maintain.

To browse what is on your site, go to **Settings > Roles**.

 ![Role list view](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC80M2JkOTMwOS0xMTRjLTQ5ZTctYWY1Yy0xMTg5NDNjNjNmN2EvMDEtcm9sZS1saXN0LnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkyNjIwOTAwLCJleHAiOjE3OTI3MDczMDB9.nhCyrdvmCL9JTp69CcXNhT5lZZIhhlStyYTuWMrdvQY)

Open any Role to see the high-level UI features it grants (sidebar, dashboard, timeline visibility) and the doctype-level permissions it carries. Most admins do not need to edit Role records; permission tuning is done in the [Role Permissions Manager](Role-Permissions-Manager.md).

 ![Role record opened](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9lMzZhMjZmMi0xMDFmLTRhYmQtYmM5Yi05MzY0NjNjNmIxNjIvMDItcm9sZS1yZWNvcmQucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MjA5MDAsImV4cCI6MTc5MjcwNzMwMH0.ePT-vjs4ok1ipFLEg4DL-Jxiwm8VefnijnryXlh5U4U)

For a complete reference of what each role grants, see the [NexWave Role Catalogue](NexWave-Role-Catalogue.md).

## Role Profiles

A Role Profile is a saved bundle of Roles. Assigning the profile to a User applies all of those Roles in one go.

Use a Role Profile when:

* Multiple users share the same job (bookkeepers, salespeople, warehouse operators).
* You want onboarding to be consistent: a new starter gets a profile, not a hand-picked list of ticked roles.
* You roll out NexWave across multiple branches or sites.

Recommended starter profiles for most NZ and AU customers:

* **Bookkeeper**: Accounts User, Employee.
* **Salesperson**: Sales User, Employee.
* **Warehouse Operator**: Stock User, Employee.
* **Office Manager**: Accounts User, Sales User, Purchase User, HR User, Employee.

To browse Role Profiles on your site, go to **Settings > Role Profile**.

 ![Role Profile list view](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC8wOTA3NGM1MC01NWVkLTQ5YzQtOTkxZi05N2JlMzU0YmU1YTYvMDMtcm9sZS1wcm9maWxlLWxpc3QucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MjA5MDAsImV4cCI6MTc5MjcwNzMwMH0.3yphDLMWywj3kfnr5U5V5ocWkZCHqEYUPG2zLs0POso)

Open a profile to see (and edit) the bundled roles. Adding a profile to a User applies all its roles in one go.

 ![Role Profile with roles assigned](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC84YTFjYTFjNS1iOTZkLTRlNjItYTdkYy02OTNiZjVjNGM3MjMvMDQtcm9sZS1wcm9maWxlLXJlY29yZC5wbmciLCJ0eXBlIjoiYXR0YWNobWVudCIsImlhdCI6MTc5MjYyMDkwMCwiZXhwIjoxNzkyNzA3MzAwfQ.mEmKFNw1v6x6e_m4f6HvU5UmOi56tAVC7OADRfLj0tc)

A note on naming: if your customer wants their own profiles, prefix the name with the company short code (for example `ACME - Bookkeeper`). It keeps custom profiles grouped together in the list and easy to spot.

**Important:** changing a Role Profile does not retroactively update users who already have it. Existing users keep the roles they were given when the profile was first applied. If you adjust a profile, re-apply it to those users.

## User Permissions

Roles grant access to a whole category of records. User Permissions narrow that access to specific records.

A few common scoping patterns:

* Restrict a user to a single **Company** in a multi-company setup.
* Limit a salesperson to one **Territory** so they only see their own customers.
* Lock a warehouse operator to a single **Warehouse**.
* Give a department head visibility of only their own **Cost Center** or **Branch**.

A typical mistake is to assign a user multi-company access without setting a default Company. New documents then fall to the wrong company and have to be cancelled and re-created. Always set the user's default Company explicitly, either on the User record or via a User Permission marked as `Is Default`.

For full coverage including the `Apply to All Document Types` toggle and worked examples, see [User Permissions and Record-Level Access](User-Permissions-and-Record-Level-Access.md).

## Practical Playbooks

### Onboarding a new finance team member


1. Create the User (see [Creating a User](Creating-a-User.md)).
2. Assign the `Bookkeeper` Role Profile (or pick `Accounts User` and `Employee` directly).
3. If your business has more than one company, add a User Permission for the relevant Company and mark it as `Is Default`.
4. Send a welcome email with login instructions.
5. Ask the user to log in once and confirm they can create a Purchase Invoice and view the Accounts Receivable Summary.

### Restricting a salesperson to a single territory


1. Open the User record.
2. Confirm they have `Sales User` and `Employee` roles.
3. Add a User Permission: `For Document Type` = Territory, `For Value` = the relevant territory record.
4. Tick `Apply to All Document Types`. The user will now only see Customers, Quotations and Sales Orders for that territory.

### Granting an external accountant read-only access for an audit


1. Create a User with the `Auditor` role only.
2. Set an expiry: enable the user's Two-Factor Authentication and put a calendar reminder to disable the account when the audit ends.
3. Optionally restrict to specific companies via User Permissions.

### Multi-branch user with branch-only visibility


1. Assign the relevant transaction roles (for example `Sales User`, `Stock User`).
2. Add a User Permission for the Branch record.
3. Tick `Apply to All Document Types`.
4. Set `Is Default = Yes` so the branch auto-fills on every new document.

## Audit & Maintenance

Healthy access control is an ongoing practice, not a one-off setup.

* **Review who has what:** the User List can be filtered by Role. The `Permitted Documents For User` report shows exactly which records a chosen user can access.
* **Deactivate leavers, do not delete:** disable the User account (`Enabled = No`) so historical records remain attributable. Delete or revoke any API keys, OAuth client credentials or Application Passwords on that user; they remain valid until removed.
* **Two-Factor Authentication:** mandatory for `System Manager` and `Accounts Manager` accounts. Strongly recommended for anyone with create or submit rights on financial documents.
* **Password policy:** configure minimum length, special-character requirements and password expiry under System Settings.
* **Quarterly access review:** schedule a recurring task to review the User List, confirm every active user is still employed, and check that elevated roles (System Manager, Accounts Manager, HR Manager) are held only by the people who need them.

## Common Pitfalls

* **System Manager is over-shared.** It is tempting to give it to everyone "just in case". Don't. Even one extra holder doubles the risk of accidental settings changes or deletions.
* **No default Company on a multi-company user.** New documents post to whichever company NexWave guesses. Always set a default.
* **Role Profile changes do not propagate.** Editing a profile only affects users assigned to it after the change. Re-apply it if you need to update existing users.
* **Forgetting to revoke API keys.** Disabling a User does not invalidate their API keys. Always remove keys when staff leave.
* **Confusing Workflows with Permissions.** Workflows control state transitions (Draft, Submitted, Approved). Permissions control who can see and edit. They work together but solve different problems.

## Step-by-step task guides

* [Creating a User](Creating-a-User.md)
* [Role Permissions Manager](Role-Permissions-Manager.md)

## Related Documentation

* [NexWave Role Catalogue](NexWave-Role-Catalogue.md): full reference of shipped roles and recommended role bundles by job function.
* [User Permissions and Record-Level Access](User-Permissions-and-Record-Level-Access.md): record-level scoping by Company, Branch, Warehouse, Territory and more.