---
question: How does Nexus decide who may do what?
kind: overview
---

# Roles & permissions

Nexus denies everything by default. A person, a group or a service account can act only where a policy attached to them allows it, and an explicit Deny always wins. Roles, features, and a module's agents, apps, workflows and pipelines all come from policies. There is no switch outside them, and no role that skips them, the platform admin included.

The Roles & permissions pages are where administrators give access, write policies, manage groups and service accounts, check a decision, and read what changed. The same pages exist at the platform, at each organization and at each workspace.

<!-- matrix -->

## Who acts: principals

A principal is whoever a policy is attached to. There are three kinds:

| Principal | Id | What it is |
|---|---|---|
| User | `usr_…` | A person, created by IAM at their first sign-in through an identity provider. |
| Group | `grp_…` | A set of users (and, at the platform, service accounts). What is attached to a group reaches every member. Groups cannot contain groups. |
| Service account | `sa_…` | A script, a CI job or a module. It signs in with a service key, never as a person. |

A group belongs to a level: the platform, an organization or a workspace. The admins of that level manage it. A group owned by an organization or a workspace takes only people of that organization.

## What decides: policies

A policy is a document of statements. Each statement has an `effect` (`Allow` or `Deny`), a list of `actions` (`<service>:<Action>`, such as `triple_store:Query` or `module:UseAgent`) and a list of `resources` (names that start with `abi:`, with `*` and `?` as wildcards):

```yaml title="Forecasting analysts"
version: "2026-10-13"
statements:
  - sid: UseTriage
    effect: Allow
    actions: ["module:UseAgent"]
    resources: ["${scope}/module:agent/harbor.tickets/Triage"]
  - effect: Deny
    actions: ["triple_store:DropGraph"]
    resources: ["*"]
```

- **Deny by default.** Nothing is allowed without an Allow that matches the action and the resource.
- **An explicit Deny wins** over any number of Allows, including those reached through another group.
- **An attachment places a policy at a level.** Attached to a principal at a workspace, an organization or the platform, a policy reaches what sits at that level, and `${scope}` stands for that level's name. Attached *below* an organization (`<organization>/*`), it also reaches every workspace inside it.

When Nexus acts for a signed-in person, both Nexus and the person must be allowed: a person never gets more through Nexus than their own policies give them.

## Built-in roles

A role is a built-in policy that IAM writes from the action catalogs of every service, by level of action: `list` and `read` for viewers, `write` for members, `admin` for admins. A new service's actions join the roles on their own.

| Role | At a workspace | At an organization | Allows |
|---|---|---|---|
| Viewer | yes | no | Every list and read action on what the level holds. |
| Member | yes | yes | Viewer, plus every write action. |
| Admin | yes | yes | Member, plus every admin action, the level's policies and groups, attaching roles below owner and policies, and View as. |
| Owner | yes | yes | Admin, plus every attachment (owners included) and owner-only actions, such as deleting the workspace or the organization. |
| Platform admin | | | Every action on everything, except sealed resources. Attached with no scope. |

The roles are cumulative, so a person needs one role per level. A role at a level stays at that level: an organization's member reaches nothing in its workspaces. An organization's owners and admins hold their role below the organization, so they reach each of its workspaces.

No role reaches the Roles & permissions pages for viewers and members. No role brings a feature or a module's agent, app, workflow or pipeline, owners included: a policy gives each one.

## Levels

| Level | Name | Opened from |
|---|---|---|
| Platform | `abi:` | Platform Settings |
| Organization | `abi:nexus:organization/<org>` | Organization Settings |
| Workspace | `abi:nexus:organization/<org>/nexus:workspace/<ws>` (`abi:nexus:workspace/<ws>` for a workspace in no organization) | Workspace settings |

A module can register containers of its own inside a workspace, such as a project, and attach policies there. A policy attached at one of them reaches what it holds and nothing else.

## Access policies and default groups

Every organization and every workspace gets an access policy and two groups when it is created:

| What | Owned by | Sub-policy of | Starts with | Attached |
|---|---|---|---|---|
| "&lt;organization&gt; access" | the platform | none | nothing allowed | to "&lt;organization&gt; admins", below the organization |
| "&lt;workspace&gt; access" | the workspace | "&lt;organization&gt; access"; none for a workspace in no organization | nothing allowed | to "&lt;workspace&gt; admins", at the workspace |
| "&lt;level&gt; members" | the level | | every person holding a role at that level | nothing |
| "&lt;level&gt; admins" | the level | | its admins and owners | the access policy |

- **"&lt;organization&gt; access" is what an organization may use.** The platform admin widens it, for example with the agents and apps of a module.
- **"&lt;workspace&gt; access" is what a workspace offers its people**, within its organization's. Its admins narrow it to hide an agent, an app or a feature from everyone below it at once.
- **A sub-policy never grants more than its parent.** Policies made for a workspace's people, such as "Forecasting analysts", are sub-policies of "&lt;workspace&gt; access": narrowing the parent narrows them at the next decision.
- **Upgraded deployments.** An organization or workspace that existed before this version keeps the access policy its upgrade made, with the features and modules its people had, but that policy is not attached to its admins group. Attach it there to let its admins and owners use it and derive from it.
- **The groups follow the roles.** Nexus keeps their members in step with who holds a role at the level. Attach to "&lt;level&gt; members" what every member should have.

## Two rules for administrators

- **Grant only what you hold.** IAM refuses a change that would let someone do something, at a level, that you cannot do there: creating or editing a policy, attaching one, adding a member to a group, inviting, binding an identity provider's group, approving a module. The refusal names the statement, the action and the resource you do not hold.
- **Derive only from what you hold.** You make a policy a sub-policy of another only if that parent is attached to you, or to one of your groups, at that level or above. The platform admin derives from any policy.

## Features and modules

Nexus lists what IAM allows. A workspace shows a feature, such as Maps or Search, only to someone a policy gives `nexus:UseFeature` on it there. It lists a module's agent, app, workflow or pipeline only to someone a policy gives `module:UseAgent`, `module:OpenApp`, `module:RunWorkflow` or `module:RunPipeline` on it there. Workspace settings › Agents, Apps and Workflows show the same list and switch nothing on or off. To hide something from a workspace, narrow or Deny it in a policy.

## Where the pages are

| Page | Path | Shown to |
|---|---|---|
| Platform Settings › Access › Roles & permissions | `/settings/roles` | anyone holding an `iam:` action at the platform |
| Organization Settings › Roles & permissions | `/organizations/<org>/settings/roles` | anyone shown a section at the organization: its owners and admins. A **Manage** picker opens each of its workspaces. |
| Workspace settings › Roles & permissions | `/workspace/<ws>/settings/permissions` | anyone shown a section at the workspace: its owners and admins |

Each section opens for whoever holds the action that lists what it shows, as IAM answers for the level:

| Section | Opens with | Platform | Organization, workspace |
|---|---|---|---|
| People & roles | `iam:ListAttachments` | yes | owners and admins |
| Groups | `iam:ListGroups` | yes | owners and admins |
| Policies | `iam:ListPolicies` or `iam:CreatePolicy` | yes | owners and admins |
| Service accounts | `iam:ListPrincipals` | yes | never |
| Module approvals | `iam:ListManifests` | yes | never |
| Simulator | `iam:Explain` | yes | never |
| Audit | `nexus:ReadSystem` | yes | never |

The platform admin sees every section. Someone given a custom policy with only `iam:ListPolicies` sees Policies and nothing else. A member or a viewer reads "You cannot manage roles or permissions here." Module approvals is where the platform admin reviews the permissions a module asks for.
