Skip to main content
Roles and permissions control which actions a user or Identity can perform and where those actions are allowed. Aion evaluates access using four connected concepts: 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 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

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

​
Roles for Agent Identities

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: 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. Project reach follows the 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.
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.
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.
Other Aion features use scope-like boundaries, but those checks are separate from role-based authorization:
  • Behavior Ion availability controls which Projects can select an implementation.
  • Request context can limit which capabilities a participant can discover for one Sequence.
  • 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 to distinguish Aion, Daemon, and linked service identities.
  • Read MCP Servers to apply permissions to capability discovery and execution.
  • Read Behavior Ions to understand implementation availability and sharing.