> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles & Permissions

> How Aion controls what users and Identities can do across resources, Projects, and environments.

**Roles and permissions** control which actions a user or
[Identity](/docs/concepts/identities) can perform and where those actions are allowed.

Aion evaluates access using four connected concepts:

| Concept         | Question it answers                           |
| --------------- | --------------------------------------------- |
| Principal       | Who is trying to act?                         |
| Role assignment | Which system roles does that principal hold?  |
| Permission      | What action does the role allow?              |
| Reach           | Which resources can that permission apply to? |

```mermaid actions={false} theme={null}
flowchart LR
  S["User or Identity<br/><small>Principal</small>"] --> A[Role assignment]
  A --> R[System role]
  R --> P[Permissions]
  A --> C[Contextual reach]
  P --> D{Allowed?}
  C --> D
  T[Target resource] --> D
```

Authentication establishes the principal. Authorization then checks whether that principal has the required
permission for the target resource in the current context.

## Principals

Aion can authorize two kinds of principals:

* **Users** act through the Aion application, API keys, and authenticated clients.
* **Agent Identities** act for application runtimes. A
  [Daemon Identity](/docs/concepts/identities#daemon-identities) is the usual principal when a configured Ion calls
  another Aion, uses an MCP server, invokes a model, or accesses another protected resource.

An external service account linked to Slack, X, Voice, or another integration authenticates that external account.
It is not the principal Aion uses for role-based authorization.

## System roles

Aion currently provides system-defined roles. Each role is a fixed bundle of permissions designed for either people
or Agent Identities.

### Workspace roles for people

| Role                | Intended access                                                                         |
| ------------------- | --------------------------------------------------------------------------------------- |
| Workspace Owner     | Full workspace administration, including membership and billing.                        |
| Workspace Admin     | The same current permission bundle as Workspace Owner.                                  |
| Workspace Developer | Build and operate Projects, Ions, Distributions, deployments, capabilities, and models. |
| Workspace Viewer    | Read workspace resources without changing or executing them.                            |

Each workspace member has one primary workspace role. Use the narrowest role that supports the person's work.

### Roles for Agent Identities

| Role               | Intended access                                                                      |
| ------------------ | ------------------------------------------------------------------------------------ |
| Project Agent      | Use eligible capabilities in the Projects associated with the Identity.              |
| Organization Agent | Use eligible capabilities, Distributions, and models across the active organization. |
| Isolated Agent     | Limit project-backed capability access to the Identity's own configured Ion.         |

Most Daemon Identities use **Project Agent**. It gives an Aion access to resources co-located in the same Project
without granting access to every Project in the organization.

## Permissions

Permissions are individual actions bundled into a role. Aion groups them into three practical categories:

| Category                   | Examples                                                                                     |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| Resource permissions       | Read, create, update, delete, or share Projects, Identities, Distributions, and deployments. |
| Agent permissions          | List or execute capabilities, invoke models, and run Distributions.                          |
| Administrative permissions | Manage workspace membership or billing.                                                      |

A role name is not enough to answer whether an operation is allowed. Aion also evaluates the permission's target and
reach. For example, two roles can both allow capability execution while applying that permission to different sets
of capabilities.

## How reach limits a permission

Reach describes how far a permission extends from a role assignment.

| Reach             | Effective boundary                                                                   |
| ----------------- | ------------------------------------------------------------------------------------ |
| Specific resource | The selected resource and any eligible child resources.                              |
| Configured Ion    | The Ion or Distribution associated with the Identity, as required by the permission. |
| Project           | The Project or Projects associated with the assigned Identity.                       |
| Organization      | Resources allowed throughout the active organization.                                |

Project reach follows the [Composer](/docs/composer) Project boundary, not the identity-rooted Aion boundary. One
Project can contain Ions that support several Aions, and one Aion can use Ions from more than one Project.

If a resource is outside the permission's effective reach, Aion denies the operation. It does not silently broaden
the assignment or treat a narrower result as though the requested boundary were available.

## Project associations and environments

Project reach comes from where an Identity participates:

* A Daemon Identity is associated with the Project containing its configured Ion.
* An Aion Identity is associated with the Projects containing its Distributions.

Matching environment names do not extend Project reach into another Project. They filter normal cross-Project
discovery when an Identity has organization-level capability access.

* A **Project Agent** can use eligible capabilities in its associated Projects.
* An **Organization Agent** can use capabilities across the organization. During automatic MCP discovery, Aion
  defaults to Projects whose environment name matches the Identity's current Project environment.
* An **Isolated Agent** is limited to project-backed capabilities configured on its own Ion.

```mermaid actions={false} theme={null}
flowchart LR
  D["Daemon Identity<br/><small>Project A · Production</small>"]
  A["Capability<br/><small>Project A · Production</small>"]
  B["Capability<br/><small>Project B · Production</small>"]
  C["Not selected by default<br/><small>Capability · Project C · Development</small>"]

  D -->|"Project Agent"| A
  D -.->|"Organization Agent · normal discovery"| B
  D ~~~ C

  classDef excluded fill:#f7f7f8,stroke:#a1a1aa,color:#52525b,stroke-dasharray: 4 3
  class C excluded
```

In this example, Project reach includes the capability in Project A. Normal organization-level discovery can also
include Project B because both Projects use `Production`. It does not select Project C by default because
`Development` does not match.

Environment names are user-maintained labels, not fixed release stages. Aion compares them without regard to
capitalization or surrounding spaces, but consistent names make the boundary easier to understand and operate.

<Note>
  Environment matching is a discovery filter, not the definition of organization reach. A surface that supports an
  explicit environment selection can search another environment when the Identity otherwise has organization-level
  access. Enabled global MCP servers are not tied to one Project environment.
</Note>

## Related visibility rules

Other Aion features use scope-like boundaries, but those checks are separate from role-based authorization:

* [Behavior Ion availability](/docs/concepts/behavior-ions#availability-and-sharing) controls which Projects can
  select an implementation.
* Request context can limit which capabilities a participant can discover for one
  [Sequence](/docs/concepts/ions#ions-and-sequences).
* Capability configuration determines whether a supported MCP, agent, or event surface is enabled on an Ion.

A resource must be both available in the current context and permitted for the acting principal. Sharing a behavior
does not grant permission to execute it, and holding a role does not enable a capability that is not configured.

## How Aion evaluates access

For each protected operation, Aion:

1. authenticates the caller and resolves the acting user or Agent Identity;
2. identifies the active organization;
3. loads the principal's active role assignments;
4. checks whether the role includes the required permission;
5. applies that permission's reach to the target resource; and
6. applies resource-specific rules, such as Project environment matching for capability discovery.

The operation succeeds only when each applicable check passes.

## Manage roles and assignments

Open **Settings > Workspace > Roles** to inspect the system roles available in the current workspace. Select a role
to review its **Permissions**, current **Assignments**, and **History**.

Role definitions and their permission settings are read-only. Assignments are managed from the surface for the
principal:

* Use **Settings > Workspace > Members** to invite people and choose their workspace role.
* Use **Resources > Identities** to review or change an Agent Identity's role.

Changing role assignments requires workspace membership-management permission.

## What to do next

* Read [Identities](/docs/concepts/identities) to distinguish Aion, Daemon, and linked service identities.
* Read [MCP Servers](/docs/resources/mcp-resources) to apply permissions to capability discovery and execution.
* Read [Behavior Ions](/docs/concepts/behavior-ions) to understand implementation availability and sharing.