> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Roles & Permissions
> Manage organization roles and permissions to control access to agents and features
# Roles & Permissions
Aster Agents uses Clerk's organization-based role and permission system to control access to features within your organization. This allows you to grant different levels of access to team members based on their responsibilities.
## Overview
All users must belong to an organization to use Aster Agents. Within each organization, users are assigned roles that determine what actions they can perform. Roles can be combined with custom permissions for fine-grained access control.
## Default Roles
### Organization Admin (`org:admin`)
Full administrative access to all organization features and settings.
**Capabilities:**
* ✅ Create, edit, and delete agents
* ✅ Manage model providers and API keys
* ✅ Configure integrations
* ✅ Manage knowledge bases
* ✅ View organization-wide analytics
* ✅ Invite and remove users
* ✅ Assign roles and permissions
* ✅ Access all admin-only features
**Use Cases:**
* Organization owners
* IT administrators
* Team leads with full platform responsibility
Admin users have unrestricted access to all features, including sensitive operations like deleting agents and viewing all user activity.
### Organization Member (`org:member`)
Standard user with read-only access to agents and limited organization visibility.
**Capabilities:**
* ✅ Chat with agents
* ✅ View agent configurations (read-only)
* ❌ Create or modify agents
* ❌ Access admin dashboard
* ❌ Manage users or settings
**Use Cases:**
* End users who only need to interact with agents
* Team members who don't need configuration access
### Organization Guest (`org:guest`)
The Guest role lets you safely invite people from **outside your company** into your organization so they can chat with your agents — without letting them see how those agents are built, what knowledge bases they use, or anything else in the Control Hub.
Think of it as a "customer-facing" seat. Your team builds the agent; the guest just uses it.
**Capabilities:**
* ✅ Chat with any agent in your organization
* ✅ View their own conversations and dashboard
* ❌ Access the Control Hub (redirected back to chat on attempted navigation)
* ❌ See knowledge bases, skills, scheduled tasks, agent configurations, integrations, or organization analytics
**Use Cases:**
* **Clients** you're delivering an agent to — they chat with it, but never see the prompts, data sources, or tools that power it
* **Partners & vendors** who need to interact with a specific workflow without being exposed to unrelated data in your org
* **Contractors** on limited engagements, where you want to revoke access in one click when the work is done
* **Beta testers & pilot users** evaluating an agent without being exposed to configuration they shouldn't change
**How to invite a guest:** in Clerk, invite them to your organization and select the **Guest** role. They sign in and land directly on the chat — no Control Hub in their navigation, and any attempt to visit it sends them back to chat.
**Access stops when you remove them.** Guests are regular Clerk organization members — when you remove them from the organization, their sessions are invalidated and they lose access to all conversations and data scoped to your org.
## Custom Roles
### Agent Manager (`org:agent_manager`)
This is a custom role designed for users who need to manage agents but don't require full admin access.
Users who can create and update agents without full administrative privileges.
**Capabilities:**
* ✅ Create new agents
* ✅ Edit existing agents
* ✅ Delete agents
* ✅ Configure agent tools and settings
* ✅ Chat with agents
* ❌ Access organization-wide analytics
* ❌ Manage users or invitations
* ❌ Configure model providers
* ❌ Access admin-only features
**Use Cases:**
* AI engineers who build and maintain agents
* Product managers who configure agent behavior
* Team members responsible for specific agents
## Permissions
Permissions provide fine-grained control over specific features. You can assign permissions to any role in your Clerk Dashboard.
### Control Hub Access
The Control Hub is where all configuration, data, and integrations live. Granting access is a single on/off decision per role — the `org:control_hub:read` permission.
| Permission | Key | Description |
| -------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Read Control Hub** | `org:control_hub:read` | Required to view the Control Hub and any of its resources (knowledge bases, skills, scheduled tasks, integrations, agent configuration). Users without this permission are redirected back to chat. |
**Grant this to every role except Guest.** Admin, Member, and any custom roles you create (Agent Manager, User Manager, etc.) should have this permission checked in the Clerk Dashboard. Leave it unchecked on Guest so external users can't see your organization's configuration.
### Agent Management Permissions
| Permission | Key | Description |
| ----------------- | -------------------------- | ---------------------------------- |
| **Create Agents** | `org:manage_agents:create` | Allows creating new agents |
| **Update Agents** | `org:manage_agents:update` | Allows editing and deleting agents |
Contact your organization admin to be assigned appropriate roles based on your responsibilities.
## Permission Hierarchy
```mermaid theme={null}
graph TD
A[Organization Admin] -->|Full Access| B[All Features]
C[Agent Manager] -->|Limited Access| D[Agent Management]
C -->|No Access| E[Admin Features]
F[Organization Member] -->|Limited Access| G[Chat + Control Hub Read]
I[Organization Guest] -->|Chat Only| J[No Control Hub]
style A fill:#e1f5fe
style C fill:#fff3e0
style F fill:#f3e5f5
style I fill:#ffebee
```
## Common Access Patterns
### Use Case: Development Team
For a team with developers who build agents and users who only chat:
| Role | Users | Access Level |
| ----------------- | ---------------- | ------------------------ |
| **Admin** | Tech Lead | Full platform access |
| **Agent Manager** | AI Engineers (3) | Agent configuration only |
| **Member** | End Users (50) | Chat access only |
### Use Case: Agency/Consultancy
For agencies building agents for multiple clients:
| Role | Users | Access Level |
| ----------------- | -------------------------- | ------------------------- |
| **Admin** | Account Manager | Full client setup |
| **Agent Manager** | Consultants (5) | Build & configure agents |
| **Member** | Client Team (20) | Use agents, view configs |
| **Guest** | External Stakeholders (10) | Chat only, no Control Hub |
### Use Case: Embedded Agents for External Users
When you onboard external parties (clients, partners) who should use your agents but not see the configuration:
| Role | Users | Access Level |
| --------- | -------------- | ----------------------------------- |
| **Admin** | Internal Team | Full platform access |
| **Guest** | External Users | Chat with agents, see own dashboard |
## Safely Inviting External Users
When you want to give someone outside your company access to your agents — a client, contractor, or partner — always invite them as a **Guest**, not a Member. This is the single most important choice for protecting your organization's data.
Guests only see the chat interface and their own conversations. Your knowledge bases, skills, prompts, integrations, and other agents remain completely hidden from them.
Use **Admin** for internal leads, **Agent Manager** for internal builders, **Member** for internal users, and **Guest** for anyone outside your company.
When an engagement ends, remove the guest from your organization in Clerk. Their session is invalidated and they immediately lose access.
Check your organization's member list monthly. Remove anyone who no longer needs access and downgrade Members to Guests if they no longer need Control Hub visibility.
**Never invite external users as Members.** Members can see your Control Hub, which exposes every knowledge base, skill, scheduled task, and agent configuration in your organization. Always use Guest for anyone outside your company.
## Security Best Practices
Only grant the minimum permissions needed for each role. Use Agent Manager instead of Admin when full access isn't required, and Guest instead of Member for external users.
Periodically review user roles and remove access for users who no longer need it. Pay special attention to external users who've been around longer than their original engagement.
Consider using different organizations for development, staging, and production environments.
Admins can view organization-wide analytics to monitor agent usage and user activity.
## Limitations & Notes
**Important Limitations:**
* Permission changes may take up to 1 minute to propagate
* Users must sign out and back in to see new permissions
## API Integration
If you're using the Aster Agents API, permissions are automatically enforced:
```bash theme={null}
# This request will fail without appropriate permissions
curl -X POST https://asteragents.com/api/agents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "New Agent",
"model": "gpt-4"
}'
# Response for users without permission:
# 403 Forbidden
# {"error": "Unauthorized: Missing org:manage_agents:create permission"}
```
## Troubleshooting
### User Can't Create Agents
Verify the user has either `org:admin` or `org:agent_manager` role in the Clerk Dashboard.
Ensure the role has both `org:manage_agents:create` and `org:manage_agents:update` permissions.
User may need to sign out and sign back in for new permissions to take effect.
### Permission Changes Not Working
1. **Clear browser cache** - Sometimes cached session data prevents updates
2. **Check Clerk Dashboard** - Verify permissions are saved correctly
3. **Wait 1-2 minutes** - Permission propagation can take time
4. **Sign out/in** - Force a fresh session token with new permissions
## Next Steps
Learn how to create and configure your first agent
Set up knowledge bases for your agents
Review our security and compliance documentation
Integrate Aster Agents into your applications
***
*For questions about roles and permissions, contact support at [patrick@asteragents.com](mailto:patrick@asteragents.com)*