Roles and groups

Belonging to an organization lets you read its members and groups. Everything else, creating agents included, comes from groups, any number of them:

• a built-in group — Organization Owner, Administrator, Maintainer or User — gives you a role on every agent of the organization; Organization Owner also lets you manage the organization, and Organization Owner, Administrator and Maintainer let you create agents;
• a custom group gives you a role on the agents it names, and only those, and can give two organization permissions: Manage organization and Create agents.

The roles are fixed sets of permissions, the same in every organization.

Permissions

Every action is a permission named by a string, <area>:<action>, such as workflows:use. The API checks these strings and the application offers only what they allow, so the two never disagree. A refusal names the permission it needed: This needs workflows:use. Within one area, write includes use and read, use includes read, and delete and personal include read. organization:manage includes every organization permission.

Organization permissions:

Permission	Allows
organization:manage	every organization permission, and Administrator on every agent; giving a custom group organization permissions
organization:write	renaming the organization; its domains and auto-onboarding
members:read	the member list with each member’s groups; the pending invitations, without their links
members:write	inviting members into groups; reading and revoking invite links; removing members; setting the groups of a member or a pending invitation
groups:read	the organization’s groups, with their members, organization permissions and agents
groups:write	renaming and deleting any custom group, and changing the members of any group, built-in ones included
agents:create	creating agents

Every member holds members:read and groups:read. agents:create comes from Organization Owner, Administrator or Maintainer, or from a custom group giving Create agents; the rest belongs to the Organization Owners.

Agent permissions:

Permission	Allows
agent:read / agent:write	the Agent page and Agent settings’ Agent and Environments sections; changing them, and creating and renaming environments
agent:delete	deleting the agent and its environments
access:write	giving a custom group a role on the agent, changing it and taking it away, in the Groups section
workflows:read	the Workflows page and the editor without editing; cases, evaluations, triggers and firings; the design agent’s threads
workflows:use	starting sessions — from the Sessions page, the Chat page, or an endpoint called with a platform sign-in; replaying a firing; retrying a deployment
workflows:write	authoring workflows and cases; running evaluations; listen windows; the editor’s chat surface; messaging the design agent
sessions:read	the Sessions page: sessions, turns, transcripts, files and decisions
sessions:use	deciding, replying, cancelling a turn, tagging a session
sessions:delete	deleting sessions
sessions:personal	other members’ chats, in every listing
skills:read / skills:write	the Skills page; creating, editing, installing and deleting skills
files:read / files:write	the Files page; uploading, editing, moving and deleting files; defining remote mounts
connections:read / connections:write	the environment’s connections and credentials (never a secret value); creating, editing, signing in to and deleting them
versions:read / versions:write	the version history; publishing, discarding, promoting and restoring
spend:read / spend:write	what the agent spent; setting spend caps

Using a connection is not configuring it: a session that calls a connection’s tool needs workflows:use, and no Connections permission.

Agent roles

Four roles, each holding everything the one before it holds:

Permissions	Reader	User	Maintainer	Administrator
agent:read, workflows:read, sessions:read, skills:read, files:read, versions:read, spend:read	✓	✓	✓	✓
workflows:use, sessions:use		✓	✓	✓
agent:write, workflows:write, skills:write, files:write, versions:write			✓	✓
agent:delete, access:write, connections:read, connections:write, spend:write, sessions:delete, sessions:personal				✓

• Reader reads the agent and its sessions, and changes nothing.
• User uses the agent: starts sessions, chats, decides and replies.
• Maintainer builds and publishes the agent. It does not configure connections or credentials, set spend caps, delete sessions, manage access or delete the agent.
• Administrator holds every agent permission.

Your role on an agent is the highest your groups give you there: your built-in group’s, and that of every custom group of yours that names the agent. If none gives you one, you hold None there. None is not a role you give; it is the absence of one. An agent you hold no role on is not listed, and opening it by its URL answers not found, as an agent of another organization would.

The application follows the role: the icon rail shows only the pages it opens (a Reader has no Chat), the top bar offers Publish with versions:write and the design agent with workflows:write, and the editor, the Agent page, a skill and the Files page open read-only without the matching write. A page reached by its URL without the permission says which one it needs.

Built-in groups

Every organization has four groups from the start:

Built-in group	Role on every agent	Also
Organization Owner	Administrator	manages the organization: its name, domains, members and groups; creates agents
Administrator	Administrator	creates agents
Maintainer	Maintainer	creates agents
User	User

The role reaches every agent of the organization, including the ones created after someone joined. Whoever creates an organization is its first Organization Owner, and so are you in your personal organization.

You can be in any number of built-in groups; the highest counts. An Organization Owner puts people in them like in any group: with Edit on a person’s row in the Organization section’s member list (see Organizations), on a pending invitation’s row for the invitee, or from the group in the Groups section.

The built-in groups are otherwise fixed: they cannot be renamed, deleted or given agents or permissions, and their names are taken, so no other group can be called User or Maintainer. An organization keeps at least one Organization Owner: taking the last one out of the group, removing them, or their leaving is refused with The organization needs an Organization Owner. A custom group giving Organization Owner does not count for this. Closing an account is never refused, though, even by the last Organization Owner.

Custom groups

A custom group has members and names agents, each with one agent role that every member of the group holds on it. Groups only add: a second group can only raise what someone may do, never lower it. To keep a person to a few agents, keep them out of the built-in groups and add them to custom groups that name those agents. Reader is given only this way.

A custom group can also give two organization permissions: Manage organization, which is everything the Organization Owner group gives, and Create agents. Only an Organization Owner checks them, and once a group gives one, only an Organization Owner changes the group.

The Groups section of the Organization & Account page lists the four built-in groups first, each with the role it gives on every agent, then the custom groups, each with its members, its Organization permissions and its agents. An agent you cannot open is counted — + 1 agent you can’t open — and never named. New group at the top right opens one dialog for the name, the members (from the organization’s members), the organization permissions (a checkbox each) and the agents with their roles (from the agents you administer), members and agents each added with the + beside its heading. The dialog has two columns: the group’s name and what it gives (organization permissions and agents) on the left, its members on the right. The pickers search as you type and offer the five best matches. A built-in group opens in the same dialog with only its members to change.

Every member may create a group. Changing a custom group — renaming it, changing its members, deleting it — needs groups:write (an Organization Owner), or, for a group that gives no organization permission, one of:

• the Administrator role on every agent the group names;
• having created it, while it names no agent.

A built-in group’s members change with groups:write alone.

Giving a group a role on an agent, changing that role or taking it away needs access:write on that agent, and is done here: the Groups section is the one place that manages who reaches an agent, and every member can read it to see which groups name an agent they open. Deleting a group takes the roles it gave away from its members, and a domain that named it as its default group names none afterwards.

An agent’s own group

Creating an agent creates a custom group named after it, with you as its member and Administrator on the new agent — numbered (Support 2) when the name is taken, a built-in group’s name included (an agent called User gets the group User 2). That is how the agent you just made stays yours to open. Add colleagues to it, or give other groups a role on the agent; the group is deleted with the agent once it names no other agent and gives no organization permission.

The design agent acts as you

A design-agent turn acts with the permissions of the member who sent the message: it reads and writes the authored tree only where they may. Each path is governed by the permission that owns it:

Path	Permission
workflows/	workflows:*
skills/	skills:*
.archmax/mounts/	files:*
.archmax/connections/	connections:*
everything else (AGENTS.md, the icon, the rest of .archmax/)	agent:*

So a Maintainer’s design-agent turn can rewrite workflows but not a connection definition. The Files page’s Agent view applies the same rule: a path you may not write is listed read-only.