***

title: Permissions & Access Control
description: Manage member roles, granular permission overrides, and resource scoping.
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.esoapp.co.uk/guides/settings/llms.txt. For full documentation content, see https://docs.esoapp.co.uk/guides/settings/llms-full.txt.

# Permissions & Access Control

Our platform utilizes a "Layered Security" model. This allows you to give broad access to your employees while strictly limiting external partners (like Truck Brokers or Clients) to only the data they need.

The system evaluates access in three sequential steps:

1. **The Base Role:** What can they do by default?
2. **Permission Overrides:** Are there specific exceptions for this person?
3. **Resource Scopes:** *Where* are they allowed to do it?

***

## 1. Global Roles (RBAC)

Every member is assigned a **Role**. This is the widest "bucket" of permissions.

| Role             | Intended For          | Key Permissions                                                         |
| :--------------- | :-------------------- | :---------------------------------------------------------------------- |
| **Admin**        | Owners & Managers     | Can manage organization settings, billing, and all inventory.           |
| **Member**       | Ops & Warehouse Staff | Can create/update inventory and packing lists. Cannot delete core data. |
| **Truck Broker** | External Carriers     | Restricted view. Can only see movements assigned to their brokerage.    |

***

## 2. Permission Overrides

Overrides allow you to fine-tune a user's access without changing their global role. This is useful for "Senior Members" who need one or two Admin-level powers.

There are two types of effects:

* **Allow:** Explicitly grants a permission (e.g., Allowing a Member to `inventory.delete`).
* **Deny:** Explicitly blocks a permission, even if their role usually allows it.

### How to Apply an Override

1. Go to **Settings > Permissions**.
2. Select a member from the list.
3. Toggle the specific permission key (e.g., `packing_lists.revert`).
4. Click **Save Overrides**.

***

## 3. Resource Scopes (The "Silo" Layer)

Scoping is the most critical feature for security. It restricts a user's visibility to specific "silos" of data.

**By default, if a user has no scopes, they can see everything in your organization.** As soon as you add one scope, the user enters **"Restricted Mode"** and can only see the resources you explicitly grant.

### Supported Scopes

* **Project Scope:** Limit a user to a specific solar farm project.
* **Client Scope:** Limit a user to a specific client's inventory.
* **Location Scope:** Limit a user to a specific warehouse or port.

<Callout intent="warning">
  **Important:** Scopes are additive. If you scope a user to *Project A* and *Project B*, they will
  see data for both, but nothing for *Project C*.
</Callout>

***

## Permission Evaluation Logic

If you are troubleshooting why a user can't see a specific item, the system follows this logic:

1. **Check Role:** Does the user's role have the permission?
2. **Check Overrides:** Is there a "Deny" override? (Deny always wins). If not, is there an "Allow" override?
3. **Check Scope:** Is the resource (Project/Location) within the user's assigned scopes?

***

## Common Configuration Scenarios

### The "External Auditor"

* **Role:** Member
* **Override:** Set all `*.read` permissions to **Allow** and all `*.create/update` to **Deny**.
* **Scope:** None (allows them to audit the whole org).

### The "On-Site Coordinator"

* **Role:** Member
* **Scope:** Only the specific **Location** (e.g., "Houston Port") and **Project** (e.g., "Golden Dune Solar") they are managing.
* **Result:** they won't see any other warehouses or unrelated projects in their dashboard.

### The "Truck Broker"

* **Role:** Truck Broker
* **Scope:** Automatically scoped to their own brokerage's movements. No manual scoping required.