Appearance
Roles & permissions
Stoa uses role-based access control with granular, per-resource permissions. This page explains the model and how to configure it.
The model in one paragraph
Every mutating action in Stoa (creating a knowledge base, changing a setting, deleting a user) is gated by a permission, expressed as a resource and an action. Permissions are bundled into roles. Users are assigned a role. When a user tries to do something, Stoa checks the user's role, the role's permissions, and whether one of those permissions covers the action being attempted. Most read-only actions, like opening a knowledge base you already have access to, aren't gated by a separate permission at all: what you can read is controlled by which resources your role can see (see "What a role can see" below), not by a view permission.
Built-in roles
Stoa ships with two default roles:
| Role | What it can do |
|---|---|
| admin | Everything. Full access to every resource and action, including system configuration, branding, audit, and user management. |
| user | Nothing, out of the box. No permissions and no assigned knowledge bases, agents, or tools until an admin grants them. |
That second row surprises new admins, so it's worth saying plainly: a fresh deployment's default user role starts empty. Before your team can do anything useful, either edit the user role to grant it the knowledge bases, agents, and tools people should see, or build custom roles for different groups of users.
Resources and actions
Permissions are organized around resources. The real set, as it stands today:
| Resource | Actions |
|---|---|
| Knowledge bases | create, update, delete, reindex |
| Agents | create, update, delete |
| Users | list, create, update, delete |
| Roles | create, update, delete |
| Instructions (prompts) | update |
| Platform settings | update, manage |
| Directory & tool integrations | manage |
| Email server | manage |
| Webhooks | manage |
| Audit log | view, view all |
| System status | view |
| Files | list, delete |
| Workflows | manage, approve |
| Exports | view |
| Feedback | view |
Each resource/action pair is a distinct permission you can grant or withhold.
Wildcards
Permissions support wildcards so you don't have to list every action individually:
- A wildcard on one resource (for example, all actions on knowledge bases) grants create, update, delete, and reindex together.
- A wildcard on one action across every resource (for example, every "view" action) grants that action everywhere it applies.
- A wildcard on everything grants every action on every resource. This is what the admin role has.
Wildcards make custom roles compact: a "Compliance Lead" role might get full access to knowledge bases and agents, plus audit viewing, and nothing else.
What a role can see
Permissions decide what kind of action a role's members can perform. Which specific resources they can see (which knowledge bases, which agents, which tools) is a separate list carried on the role itself, not a per-resource "share with this person" panel.
When you create or edit a role, alongside its permissions you pick the specific knowledge bases, agents, and tools that role's members can access. A user only sees what their role has been given access to. This means access for a group of people is managed in one place (the role), rather than by visiting every knowledge base individually to share it.
Custom roles
To create a custom role:
- Open the user menu, choose Team, then Roles.
- Click Create role.
- Give it a name and description.
- Tick the permissions it should have.
- Choose the specific knowledge bases, agents, and tools members of this role should have access to.
- Save.
Once created, the role appears in the role dropdown when you create or edit a user.
Directory-provisioned users
If you use Active Directory or LDAP, every auto-provisioned user is created with the default user role. There's no automatic mapping from directory group membership to a Stoa role today: if someone needs a different role, reassign it manually from the Users screen after their account exists. See Active Directory.
Auditing role changes
Every change to roles and role assignments is recorded in the Audit log. If you ever need to answer "who gave this user access," the audit log has it.
Next
- Active Directory for how directory sign-in interacts with roles.
- Audit logging to verify access decisions.
- User Guide for what your end users see.