Roles and Permissions
Trinity uses a 4-tier role system to control who can create agents, manage existing ones, or just interact with them.
Role Hierarchy
admin
HighestCan create and manage all agents. Password login required.
creator
DefaultCan create agents and manage own agents only. Email whitelist signup.
operator
Cannot create agents. Can manage assigned agents only. Email whitelist, role manually set.
user
Cannot create or manage agents. Public links only.
Roles are hierarchical: admin > creator > operator > user. Higher roles inherit all permissions of lower roles.
How It Works
Default Role Assignment
When you sign up via email (if whitelisted), you receive the creator role by default. This allows you to immediately create and manage agents.
Admins can change a user's role at any time via Settings.
Role-Based Restrictions
| Action | Required Role |
|---|---|
| Create agents | creator or above |
| Delete agents | Owner or admin |
| Configure agent settings | Owner or admin |
| Run tasks and schedules | operator or above (with access) |
| Chat with shared agents | Any authenticated user |
| Use public links | Anyone (no auth required) |
Managing User Roles
Admin only: Navigate to Settings and scroll to the User Management section.
Find the user in the table.
Select a new role from the dropdown.
The change takes effect immediately on their next request.
You cannot change your own role.
For Agents
User roles are stored in the users table. The role is checked on each API request via the require_role() dependency.
| Endpoint | Method | Description |
|---|---|---|
| /api/users | GET | List all users (admin-only) |
| /api/users/{username}/role | PUT | Change a user's role (admin-only) |
Request body:
{"role": "operator"}Valid roles: admin, creator, operator, user
Limitations
Role changes apply immediately but don't invalidate existing JWT tokens.
Public link users have no database entry — they operate at the user level.
Admins cannot demote themselves.