--- title: "Roles and Permissions" description: "How Orbit blends role-based and condition-based access control — managed roles, custom roles, permissions, and why scoping means some users see fewer records." url: "https://support.pr-5.orbit.do/en/advanced-features/roles-and-permissions" locale: "en" apps: ["mission"] lastReviewed: "2026-10-26" --- # Roles and Permissions How Orbit blends role-based and condition-based access control — managed roles, custom roles, permissions, and why scoping means some users see fewer records. ## Overview In Orbit, effective management of user access is crucial. The 'Roles' feature is a cornerstone of our system and empowers you to customise access control with precision and flexibility. This essential tool lets you define who can do what within Orbit, ensuring your operations run smoothly and securely. Roles and Permissions in Orbit are designed for maximum flexibility and control, seamlessly blending Role-Based Access Control (RBAC) with the nuanced capabilities of Attribute-Based Access Control (ABAC). The 'Roles' section within Orbit MissionControl’s settings allows users to define and customise the access control to most objects within the Orbit system. **Key Highlights** * **Managed Roles**: Orbit offers a range of pre-configured roles, each designed to meet standard operational requirements. Predefined managed roles provide a foundation, encompassing standard access patterns suitable for common user types. These roles serve as a starting point, ensuring basic operational needs are met efficiently. * **Custom Roles**: For those unique operational needs, custom roles allow you to tailor access controls. These roles can be built from scratch or modeled on existing managed roles, providing flexibility and precision in defining user capabilities. * **Conditions**: Orbit’s 'Conditions' in permissions allow precise access control. Tailor permissions for specific scenarios, like restricting `Vehicle` actions by weight or defining webhook access by URL content. > **Warning:** **Important**: This feature is a powerful tool that allows each organisation to tailor Orbit to their own unique requirements. However, while it grants significant flexibility, improper configuration can lead to unintended access restrictions or exposure of sensitive information. Exercise great caution when adjusting these settings — review your changes thoroughly and understand their impact before saving. ## Key Concepts and Features ### **Clarifying Users, Roles, and Permissions** It's essential to distinguish between users, roles, and permissions within Orbit to set up and manage access effectively. * **Users**: These are individuals (`Shippers`, `Operators` & `Carriers`) who operate within the Orbit ecosystem. By default, `Operator` users are assigned managed administrator roles, which grant them comprehensive read and write access across Orbit. * **Roles**: Roles are assigned to users and define their access levels. E.g. the 'Operator Administrator' managed role provides broad access, other roles can be specified to tailor user permissions more closely to their responsibilities or their respective user group (e.g. `Shipper`). * **Permissions**: These are specific actions that roles may or may not perform on Orbit entities, such as creating, viewing, or modifying data. Each role encompasses a set of permissions that, in turn, define the capabilities of the user holding that role. ### **Roles** #### **Managed Roles** Managed roles, provided by Orbit, are pre-established roles equipped with predefined permissions designed to address standard operational needs efficiently. These roles are locked for editing to maintain system integrity but can serve as a starting point for creating custom roles tailored to specific organisational requirements. Managed roles are maintained by Orbit and will be automatically updated to guarantee compatibility with system updates and new features. Orbit provides seven managed roles for users. They cover the most common needs of the three party types: the logistics operator, its shippers, and its carriers. * **Operator Administrator** — full access to run the operation and manage settings, users, and other operators. * **Operator Member** — day-to-day operational access, without the ability to change settings or other operators' roles. * **Shipper Administrator** — manages a shipper organisation and its users, and sees that shipper's own bookings. * **Shipper Member** — books and tracks transports for their shipper, with a narrower reach than the administrator. * **Carrier Administrator** — manages a carrier organisation, its team, its drivers and its vehicles, and works the tours offered to that carrier. It may create drivers of its own carrier, and create and change the carrier's vehicles; it retires a vehicle by setting it inactive and cannot delete one. * **Carrier Member** — works a carrier's assigned tours and offers, including the carrier's own rate. * **Driver** — the narrowest role: executes an assigned `Tour` — its stops, loads, and proof capture — without seeing offers, pricing, or customer records. Orbit also provides four managed roles for API keys only: **Operator API Key Full Access**, **Operator API Key Read Only**, **Carrier API Key Full Access** and **Carrier API Key Read Only**. The roles settings in Orbit MissionControl mark them "API Keys Only". They cannot be assigned to a user, and no role selection for users offers them. A carrier key with **Carrier API Key Full Access** can create and change the drivers and vehicles of its own carrier, never those of another carrier. You choose a key's role when you create it and can change it later, see [API keys](https://support.pr-5.orbit.do/en/advanced-features/api-keys). A key can also hold one of your own roles, when the role is meant for the key's kind of user and contains no condition that names a single user or team. The Orbit API checks every request against the role of its key. **Operator API Key Full Access** has every right of the Operator Administrator, and every key created before keys had roles holds it. **Operator API Key Read Only** reads the same data and gets status 403 for every change. #### **Custom Roles** Custom roles offer personalised access control. They can be crafted from the ground up or based on existing roles. To use an existing role as a starting point, right-click on it in Orbit MissionControl and select **Use as Template**. By creating custom roles, you can align the Orbit system closely with the unique functions and responsibilities within your organisation. Every role in the Orbit system, whether managed or custom, contains the following fields: * **Name**: A distinctive and recognisable name assigned to your role. * **Description (optional)**: A concise explanation of what the role is intended for, aiding in clarity and understanding. * **Recommended User Types (optional)**: Identifies the ideal user type for the role, such as shipper-user, operator-user, or carrier-user. It can be left unspecified or include multiple types if the role spans across various user functions. This helps to guide the administrator when assigning roles to users in Orbit MissionControl. Also, this helps narrowing down available roles for specific user types. For example, when inviting carrier users to the Orbit Dispatch application, you can only select roles that include carrier-user in its recommended user types. Orbit enforces these recommendations on every new assignment, including assignments through Orbit’s API: a role whose recommended user types do not include the user's type cannot be assigned to that user. A role whose recommended user types are left unspecified can still be assigned to any user through Orbit’s API. * **Status**: Denotes the current state of the role, either active or inactive. An inactive status effectively removes all access privileges for users assigned to that role. #### Editing and Assigning Roles Roles are dynamic and can be edited as organisational needs evolve. You can add or remove permissions, tweak conditions, or revise the role's details and activity status. Be aware that to make these changes, your user must be granted the necessary permissions over the 'Role' Entity. All changes are recorded and can be reviewed in the role status log. To link a role with a user, navigate to Settings → Users in Orbit MissionControl and select the user you wish to update. Just as with the roles, your user must be granted permissions over the 'OperatorUser' entity in order to proceed with this. #### Permissions Roles control access through permissions. Users can assign any number of permissions to a role. Each permission consists of: * **Authority:** This denotes whether the role has permission to perform ('can') or is denied from performing ('can not') an action on an Entity. As a best practice, keep the following in mind: Direct logic is easier to reason about, so use positive rules (’can’) as much as possible! This allows to keep permissions clean, and more readable and reduces the risk of giving wrong permissions to the wrong users. > **Give permissions, don't take them away** * **Action**: Actions are the tasks that a role is authorised to execute: create, read, update, or delete. For instance, a role with 'can create' authority for `Vehicles` has the capacity to create new `Vehicles` in Orbit MissionControl. * **Entity**: The subject of the action (e.g., `Vehicle`, `CarrierUser` (Driver), `Region`). This list is ever-expanding to make sure that almost all objects within the Orbit ecosystem can be included in role definitions. The current list of entities includes: * `APIKey` * `Callout` * `Carrier` * `CarrierUser` * `CarrierTeam` * `Insights` * `LoadType` * `OperatorTeam` * `OperatorUser` * `OperatorUserInvite` * `Order` * `PropertyDefinition` * `Region` * `Role` * `Shipment` * `Shipper` * `ShipperAddress` * `ShipperTeam` * `ShipperUser` * `ShipperUserInvite` * `Shop` * `ShopApp` * `ShopSignUpConfig` * `Tour` * `TourPrice` * `Vehicle` * `VehicleClass` * `Voucher` * `Webhook` * `WorkbenchSetting` * **Condition** (optional): Conditions provide granularity to permissions, allowing roles to be specific about the circumstances under which they apply. The applicability of conditions is tailored to the nature of the entity in question. For example, a condition for a `Vehicle`-related permission could limit actions to `Vehicles` with a weight capacity exceeding 1000kg, whereas a Webhook-related permission could check the presence of a specific string in the endpoint URL. ## Use Case Example ### Fleet manager in Tokyo * **Role Name**: *Fleet Manager Tokyo* * **Permission**: `can create Vehicle` * **Condition**: License plate begins with ‘TKA’ This configuration means that users with the 'Fleet Manager Tokyo' role can create `Vehicles` that have a license plate starting with the letters ‘TKA’. Users will not be allowed to do or see anything else on the platform as all permissions need to be explicitly granted. ### Lock completed orders Spaceport Shipping Co. hands every completed `Order` to its accounting system. Once an order is done, its operations team in Lyon should leave it alone, and only the administrators, Julia and Max, should correct it. Julia sets up a role for the team: 1. **Copy the role** In Orbit MissionControl, open **Settings** → **User Management** → **Roles**, right-click **Operator Member** and select **Use as Template**. Name the new role *Operations Lyon*. 2. **Lock the order** Hover over the `Order` row and select **Add Condition**. Choose **cannot** and **update**, set the condition to Status **equals** `Completed`, and save it. 3. **Forbid deleting** Add a second condition on the `Order` row: **cannot**, **delete**, Status **equals** `Completed`. Do the same on the `Tour` row: **cannot**, **delete**, Status **equals** `Completed`. 4. **Assign the role** Assign *Operations Lyon* to the members of the team. The role keeps every permission of **Operator Member** and adds three rules: | Entity | Rule | Condition | | ------- | --------------------- | ----------------------------- | | `Order` | **cannot** **update** | Status **equals** `Completed` | | `Order` | **cannot** **delete** | Status **equals** `Completed` | | `Tour` | **cannot** **delete** | Status **equals** `Completed` | Which rules you set depends on what may still change after completion. In the example, Julia locks the order and forbids deleting completed orders and tours; the tour itself stays editable. To freeze the tour as well, add the same rule with **update** on the `Tour` row. This example uses **cannot** rules, although positive rules are the better habit. For a status, the condition editor offers only **equals**, so a **can** rule cannot say "every status except `Completed`". A **cannot** rule with a condition is added next to the role's **update** or **delete** permission instead of replacing it, so the team keeps editing and deleting orders and tours in every other status. When a user with this role opens a completed `Order` in Orbit MissionControl, the order page shows **Read-only** with the text "This order is completed and locked for your role." When an accounting integration is active, it continues "Corrections are made in the accounting system or by a user whose role may edit completed orders." Otherwise it continues "Changes are made by a user whose role may edit completed orders." What the team can still do on a completed order: * **Shipments:** change the stops and data of the order's shipments, as long as the order price (and, if set up that way, the tour price) is kept. Choose **Preserve** for the order (and, if set up that way, for the tour) when Orbit MissionControl asks how to align the product price. An edit that would **Recalculate** a locked order (or, if set up that way, tour) is refused as a whole, and nothing is saved. * **Documents and comments:** post comments to the order, and upload documents when the role has the **Document** permissions. The lock does not touch them; **Operator Member** has no Document permissions to begin with, so a role copied from it cannot upload documents on any order. * **Tour review:** select **Complete Review** on a tour in `Review Required`. The tour and its order complete as usual. What the role locks on a completed order: * **Order details:** the customer, the invoice recipient, the customer reference, the customer comment and internal comment fields, the price and the properties. * **Order actions:** the actions in the order's menu, including sending the order to the accounting system by hand and sending a failed submission again. Cancelling a pending submission is locked too. * **The tour:** deleting the completed `Tour`; everything else on the tour stays as on any other tour. **Send automatically when an order is completed** keeps working. Orbit submits the order itself when the order is completed, whatever the role of the user who completed the review. Users with **Operator Administrator** keep editing completed orders, so Julia and Max make the corrections. Any other role without these conditions can do the same. > **A toggle removes the lock:** To lift the lock, delete the condition with its delete icon. Selecting the **update** or **delete** toggle on the `Order` or `Tour` row removes it as well: the toggle replaces every **update** or **delete** rule of that row respectively, conditions included. Check both rows after you change a toggle. > **Why a colleague may see fewer records than you:** Because access is scoped by role and by condition, two people can open the same list and see different amounts. A shorter list, a hidden price, or a record that isn't visible to a particular user is Orbit applying that user's role as configured — it is working as designed, not a fault or missing data. If someone needs to see more, adjust their role rather than looking for a workaround. ## FAQ **Q: Can a user with a locked role still send a completed order to accounting?** No. Sending an order by hand is a change to the order, so the lock covers it, and so does sending a failed submission again or cancelling a pending one. **Send automatically when an order is completed** is not affected: Orbit submits the order itself. A user whose role may edit completed orders, such as **Operator Administrator**, sends a failed submission again. **Q: What happens if a user with a locked role recalculates the price of a completed order?** Orbit MissionControl refuses the change and saves nothing. This applies when a shipment edit would **Recalculate** the price of the completed order (or, if set up that way, its completed tour). The same edit with **Preserve** for every locked price is saved.